repo: opensearch action: blob revision: path_from: src/mediawiki-export-full.xml revision_from: refs/heads/master: path_to: revision_to:
blob of:
/ mediawiki-export-full.xml
refs/heads/master:/src/mediawiki-export-full.xml
OpenSearch http://www.opensearch.org/Home MediaWiki 1.10.0 first-letter Media Special Talk User User talk OpenSearch OpenSearch talk Image Image talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk About 1407 1421 2006-07-23T00:53:42Z DeWitt 2 [[About]] moved to [[About OpenSearch.org]] #REDIRECT [[About OpenSearch.org]] About OpenSearch.org 1406 1419 2006-07-23T00:53:11Z DeWitt 2 == About OpenSearch.org == 1420 2006-07-23T00:53:42Z DeWitt 2 [[About]] moved to [[About OpenSearch.org]] == About OpenSearch.org == 1423 2006-07-23T00:54:31Z DeWitt 2 /* About OpenSearch.org */ ... todo ... 1618 2006-08-09T21:49:18Z DeWitt 2 The [http://opensearch.org/ opensearch.org] website is made available by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. 1621 2006-08-10T16:08:41Z DeWitt 2 The [http://opensearch.org/ opensearch.org] website is made available by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. 1629 2006-08-11T03:36:49Z DeWitt 2 The [http://opensearch.org/ opensearch.org] website was created and is maintained by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. 1660 2006-08-25T13:46:35Z DeWitt 2 The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1710 2006-09-05T20:33:43Z DeWitt 2 ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1713 2006-09-05T20:50:19Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by [[User:DeWitt|DeWitt]] and a cadre of small badgers. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1720 2006-09-05T20:55:50Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by the OpenSearch community. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1721 2006-09-05T20:56:08Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by the [[Community/OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1722 2006-09-05T20:56:22Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1725 2006-09-05T21:04:59Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by members of the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1726 2006-09-05T21:12:33Z DeWitt 2 Protected "[[About OpenSearch.org]]" [edit=sysop:move=sysop] ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. Maintained by members of the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1746 2006-09-07T23:04:52Z DeWitt 2 /* Credits */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This site is maintained by members of the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and uses the [http://meta.wikimedia.org/wiki/OpenSearch OpenSearch plugin] developed by [http://wiki.case.edu/User:Gregory.Szorc Gregory Szorc]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1902 2007-02-10T02:50:56Z DeWitt 2 /* Colophon */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This site is maintained by members of the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki] and is maintained by [http://blog.unto.net/ DeWitt Clinton]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. 1903 2007-02-10T02:51:12Z DeWitt 2 /* Colophon */ ==Credits== The [http://opensearch.org/ opensearch.org] website was created by [http://a9.com A9.com, Inc.], an [http://www.amazon.com Amazon.com] company. This site is maintained by members of the [[Community/OpenSearch community|OpenSearch community]]. ==Colophon== This website is powered by [http://www.mediawiki.org/wiki/MediaWiki MediaWiki]. ==Contributing== Please read the [[Community/Guidelines|community guidelines]] if you would like to contribute to this website. Community/Guidelines 1459 1650 2006-08-21T14:57:27Z DeWitt 2 OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered using [http://mediawiki.org MediaWiki], the same [[w:Wiki]] software that is used to power [http://wikipedia.org Wikipedia]. 1651 2006-08-21T15:45:08Z DeWitt 2 ==Introduction== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered using [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. ==Rules== As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information (in the appropriate places) are often welcome. If you would like to propose a new OpenSearch extension, please use the [[Community/Proposal namespace|Proposal namespace]]. A good rule of thumb is: : ''When in doubt, err on the side of caution.'' Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. And it should go without saying that this site is exclusively ==Rules== * Please post only content related to OpenSearch. This site is here for just that. [http://wikipedia.org|Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. Be sure to give credit where credit is due. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1652 2006-08-21T15:50:56Z DeWitt 2 ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered using [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please post only content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please use the [[Community/Proposal namespace|Proposal namespace]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1653 2006-08-21T15:58:22Z DeWitt 2 /* Getting started */ ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please post only content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please use the [[Community/Proposal namespace|Proposal namespace]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1654 2006-08-21T16:18:18Z DeWitt 2 /* House rules */ ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please use the [[Community/Proposal namespace|Proposal namespace]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1669 2006-09-04T15:34:28Z DeWitt 2 ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please use the [[Community/Proposal guidelines|proposal guidlines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1670 2006-09-04T15:34:48Z DeWitt 2 ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please follow the [[Community/Proposal guidelines|proposal guidlines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1675 2006-09-04T15:41:59Z DeWitt 2 /* House rules */ ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of OpenSearch.org editors. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please follow the [[Community/Proposal guidelines|proposal guidelines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1940 2007-11-10T18:19:01Z DeWitt 2 ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of [[Community/OpenSearch_community|OpenSearch.org editors]]. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please follow the [[Community/Proposal guidelines|proposal guidelines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! 1968 2007-12-22T11:55:04Z Trafficdiffusion 117 TrafficDiffusion.com ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of [[Community/OpenSearch_community|OpenSearch.org editors]]. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please follow the [[Community/Proposal guidelines|proposal guidelines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. TrafficDiffusion.com provides advanced performance_based marketing solutions that help marketers increase online leads and sales. This includes maximizing performance for your ads and ensuring that our network is comprised of only the highest quality websites. Please fell out for your affiliation system "EAYSY TO USE" at http://www.trafficdiffusion.com Membership ‘BASIC’ is FREE, Register now for FREE! 1969 2007-12-22T11:55:44Z Trafficdiffusion 117 TrafficDiffusion.com ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of [[Community/OpenSearch_community|OpenSearch.org editors]]. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. TrafficDiffusion.com provides advanced performance_based marketing solutions that help marketers increase online leads and sales. This includes maximizing performance for your ads and ensuring that our network is comprised of only the highest quality websites. Please fell out for your affiliation system "EAYSY TO USE" at http://www.trafficdiffusion.com Membership ‘BASIC’ is FREE, Register now for FREE! 1971 2007-12-22T15:10:34Z DeWitt 2 Reverted edits by [[Special:Contributions/Trafficdiffusion|Trafficdiffusion]] ([[User talk:Trafficdiffusion|Talk]]); changed back to last version by [[User:DeWitt|DeWitt]] ==Getting started== OpenSearch.org is designed to offer the community a place to discover and contribute to the OpenSearch effort. This site is powered by [http://mediawiki.org MediaWiki], the same [http://en.wikipedia.org/wiki/Wiki Wiki] software that is used to power [http://wikipedia.org Wikipedia]. As such, it offers you, the reader, an opportunity to contribute back. If you would like to contribute, either by suggesting improvements and corrections, or by adding new content of your own, you will first need to create an account. Please use the [[Special:Userlogin|Log in]] form to add yourself to the list of [[Community/OpenSearch_community|OpenSearch.org editors]]. As the content on OpenSearch.org will be considered by many to be canonical, it is important that we work together to offer only the best advice for OpenSearch users. Certain pages, such as the OpenSearch 1.1 specification itself, and any other "permanent" page, are [http://meta.wikimedia.org/wiki/Protected_pages protected] to prevent against unexpected changes. If you would like to comment on a protected page, please use the associated [http://meta.wikimedia.org/wiki/Talk_pages Talk page]. ==House rules== * Please only post content related to OpenSearch. :: This site is here exclusively for information about OpenSearch. [http://wikipedia.org Wikipedia] is a great place for other topics. * Please do not post spam or commercial content and/or links. :: Doing so will get your account and your IP banned nearly instantly, so please, don't. * Please respect other people and their work. :: Use your best judgement if editing a page. Typos and grammar fixes are usually safe. Pointers to additional information are welcome (in the appropriate places). Please be especially careful if you are making an edit that could change the meaning or interpretation of existing work. * Please do not plagiarize. :: Be sure to give credit where credit is due. * Please post content in the right place. :: If you would like to propose a new OpenSearch extension, please follow the [[Community/Proposal guidelines|proposal guidelines]]. * Please err on the side of caution. :: Use the Talk pages to ask questions if you are not sure about a change. It is much better to start a dialog than to see an [http://en.wikipedia.org/wiki/Wikipedia:Edit_war edit war] break out. ==Reminder== A reminder that this is site is an optimistic experiment. If it turns out that running a community wiki is subject to abuse then plans will have to adjust accordingly. But in the meantime, thank you, have fun, and welcome to OpenSearch.org! Community/JSON Formats 1700 2165 2008-11-25T18:43:56Z DeWitt 2 New page: A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview <pre><nowiki>{ "resp... A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> 2166 2008-11-25T19:11:23Z DeWitt 2 /* Microsoft Live Search API 2.0 */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> 2167 2008-11-25T19:20:05Z DeWitt 2 /* Google Ajax Search API */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> 2168 2008-11-25T19:20:39Z DeWitt 2 /* Yahoo Web Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> 2169 2008-11-25T19:45:52Z Weblivz 445 A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems &QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> 2170 2008-11-25T19:48:49Z Weblivz 445 A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> 2171 2008-11-25T21:17:36Z AndrewTurner 66 A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[{"report": {"score":0,"zip":null,"wait_time":null,"updated_at":"2008-11-15T16:19:16Z","text":"Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.","display_text":"Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.","name":"Nathan Freitas","rating":null,"polling_place":null,"icon":"http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg","id":12605,"audio_link":null,"display_html":"<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>","source":"TWT","location":{"location": {"country_code":"US","updated_at":"2008-10-30T02:43:27Z","thoroughfare":null,"postal_code":null,"administrative_area":"NY","point":{"type":"Point","coordinates":[-73.971043,40.675234]},"id":404,"locality":"Brooklyn","sub_administrative_area":null,"filter_list":null,"address":"Brooklyn, NY, USA","geo_source_id":1,"created_at":"2008-10-30T02:43:27Z"}},"reporter":{"twitter_reporter": {"name":"Nathan Freitas","icon":"http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg"}},"created_at":"2008-11-15T16:19:07Z"}},{"report": {"score":null,"zip":"84105","wait_time":0,"updated_at":"2008-11-15T05:12:44Z","text":"Telephone report to 208-272-9024 #good","display_text":"Telephone report to 208-272-9024 #good","name":"Telephone User","rating":100,"polling_place":null,"icon":"http:\/\/votereport.us\/images\/phone_icon.jpg","id":12599,"audio_link":"http:\/\/calls.votereport.us\/1226725807.587.gsm","display_html":"<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>","source":"TEL","location":{"location": {"country_code":"US","updated_at":"2008-11-15T05:12:44Z","thoroughfare":null,"postal_code":"84105","administrative_area":"UT","point":{"type":"Point","coordinates":[-111.8628205,40.7345053]},"id":5986,"locality":"Salt Lake City","sub_administrative_area":null,"filter_list":null,"address":"Salt Lake City, UT 84105, USA","geo_source_id":1,"created_at":"2008-11-15T05:12:44Z"}},"reporter":{"phone_reporter": {"name":"Telephone User","icon":"\/images\/phone_icon.jpg"}},"created_at":"2008-11-15T05:12:44Z"}}] </nowiki></pre> 2172 2008-11-25T22:18:29Z DeWitt 2 /* VoteReport API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> 2173 2008-11-25T22:18:54Z DeWitt 2 /* VoteReport API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> 2174 2008-11-25T22:20:46Z DeWitt 2 /* eBay Shopping API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> 2190 2008-12-29T07:32:52Z DeWitt 2 /* VoteReport API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{"Timestamp":"2008-11-25T19:44:28.387Z","Ack":"Failure","Errors":[{"ShortMessage":"Application ID invalid.","LongMessage":"Application ID invalid.","ErrorCode":"1.20","SeverityCode":"Error","ErrorClassification":"RequestError"}],"Build":"e591_core_Bundled_7560815_R1","Version":"591"} </nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> 2191 2008-12-29T07:34:47Z DeWitt 2 /* eBay Shopping API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{ "Ack": "Failure", "Build": "e591_core_Bundled_7560815_R1", "Errors": [ { "ErrorClassification": "RequestError", "ErrorCode": "1.20", "LongMessage": "Application ID invalid.", "SeverityCode": "Error", "ShortMessage": "Application ID invalid." } ], "Timestamp": "2008-11-25T19:44:28.387Z", "Version": "591" }</nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> 2192 2008-12-29T07:34:58Z DeWitt 2 /* VoteReport API Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{ "Ack": "Failure", "Build": "e591_core_Bundled_7560815_R1", "Errors": [ { "ErrorClassification": "RequestError", "ErrorCode": "1.20", "LongMessage": "Application ID invalid.", "SeverityCode": "Error", "ShortMessage": "Application ID invalid." } ], "Timestamp": "2008-11-25T19:44:28.387Z", "Version": "591" }</nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> 2193 2008-12-29T07:35:12Z DeWitt 2 /* Twitter Search */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{ "Ack": "Failure", "Build": "e591_core_Bundled_7560815_R1", "Errors": [ { "ErrorClassification": "RequestError", "ErrorCode": "1.20", "LongMessage": "Application ID invalid.", "SeverityCode": "Error", "ShortMessage": "Application ID invalid." } ], "Timestamp": "2008-11-25T19:44:28.387Z", "Version": "591" }</nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> 2202 2009-02-12T20:10:15Z Derek 563 added nytimes article search A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{ "Ack": "Failure", "Build": "e591_core_Bundled_7560815_R1", "Errors": [ { "ErrorClassification": "RequestError", "ErrorCode": "1.20", "LongMessage": "Application ID invalid.", "SeverityCode": "Error", "ShortMessage": "Application ID invalid." } ], "Timestamp": "2008-11-25T19:44:28.387Z", "Version": "591" }</nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> == The New York Times Article Search API == Reference: http://developer.nytimes.com/docs/article_search_api/ Query: http://api.nytimes.com/svc/search/v1/article?query=(field:)keywords (facet:[value])(¶ms)&api-key=your-API-key Response: <pre><nowiki> { "facets" : { "classifiers_facet" : [ { "count" : 83, "term" : "Top/News" }, { "count" : 74, "term" : "Top/Classifieds/Automobiles/Topics/Wheel Spin" }, { "count" : 69, "term" : "Top/News/Sports" }, { "count" : 18, "term" : "Top/Features/Travel/Guides/Destinations/North America" }, { "count" : 18, "term" : "Top/Features/Travel/Guides/Destinations/North America/United States" }, { "count" : 15, "term" : "Top/Features/Travel/Guides/Destinations/Europe" }, { "count" : 10, "term" : "Top/Classifieds/Automobiles" }, { "count" : 10, "term" : "Top/News/Business" }, { "count" : 6, "term" : "Top/Features/Magazine" }, { "count" : 6, "term" : "Top/Features/Travel/Escapes" }, { "count" : 6, "term" : "Top/Features/Travel/Guides/Destinations/Central and South America" }, { "count" : 6, "term" : "Top/News/World/Europe" }, { "count" : 5, "term" : "Top/Classifieds/Job Market/Job Categories/Fashion, Beauty and Fitness" }, { "count" : 5, "term" : "Top/Classifieds/Job Market/Job Categories/Media, Entertainment and Publishing" }, { "count" : 5, "term" : "Top/News/Obituaries" } ], "des_facet" : [ { "count" : 126, "term" : "AUTOMOBILE RACING" }, { "count" : 22, "term" : "AUTOMOBILES" }, { "count" : 15, "term" : "BIOGRAPHICAL INFORMATION" }, { "count" : 8, "term" : "INDIANAPOLIS 500 (AUTO RACE)" }, { "count" : 8, "term" : "PROFESSIONAL ATHLETICS" }, { "count" : 5, "term" : "ACCIDENTS AND SAFETY" }, { "count" : 4, "term" : "DEATHS (OBITUARIES)" }, { "count" : 4, "term" : "FORMULA ONE GRAND PRIX (AUTO RACE)" }, { "count" : 4, "term" : "MERGERS, ACQUISITIONS AND DIVESTITURES" }, { "count" : 4, "term" : "TELEVISION" }, { "count" : 4, "term" : "TRAVEL AND VACATIONS" }, { "count" : 3, "term" : "APPAREL" }, { "count" : 3, "term" : "FINANCES" }, { "count" : 2, "term" : "ADVERTISING" }, { "count" : 2, "term" : "ADVERTISING AND MARKETING" } ], "geo_facet" : [ { "count" : 5, "term" : "UNITED STATES" }, { "count" : 4, "term" : "BRAZIL" }, { "count" : 4, "term" : "EUROPE" }, { "count" : 4, "term" : "NEW YORK CITY" }, { "count" : 3, "term" : "MONACO" }, { "count" : 2, "term" : "AMERICA" }, { "count" : 2, "term" : "FRANCE" }, { "count" : 2, "term" : "GREAT BRITAIN" }, { "count" : 2, "term" : "INDIANAPOLIS (IND)" }, { "count" : 2, "term" : "INDIANAPOLIS (INDIANA)" }, { "count" : 2, "term" : "JAPAN" }, { "count" : 2, "term" : "LONG ISLAND (NY)" }, { "count" : 2, "term" : "SAHARA DESERT" }, { "count" : 1, "term" : "AFRICA" }, { "count" : 1, "term" : "ALABAMA" } ], "org_facet" : [ { "count" : 12, "term" : "FORMULA ONE" }, { "count" : 5, "term" : "NATIONAL ASSN OF STOCK CAR AUTO RACING" }, { "count" : 4, "term" : "FORD MOTOR CO" }, { "count" : 4, "term" : "INDIANAPOLIS MOTOR SPEEDWAY" }, { "count" : 2, "term" : "CHAMPIONSHIP AUTO RACING TEAMS" }, { "count" : 2, "term" : "ESPN" }, { "count" : 2, "term" : "HONDA MOTOR CO" }, { "count" : 2, "term" : "JAGUAR CARS LTD" }, { "count" : 2, "term" : "JAGUAR PLC" }, { "count" : 2, "term" : "MASERATI SPA" }, { "count" : 2, "term" : "MITSUBISHI MOTORS CORP" }, { "count" : 2, "term" : "PHILIP MORRIS COMPANIES INC" }, { "count" : 2, "term" : "PORSCHE AG" }, { "count" : 1, "term" : "AL QAEDA" }, { "count" : 1, "term" : "ALFA ROMEO OF ITALY" } ], "per_facet" : [ { "count" : 3, "term" : "ANDRETTI, MICHAEL" }, { "count" : 3, "term" : "FITTIPALDI, EMERSON" }, { "count" : 3, "term" : "MANSELL, NIGEL" }, { "count" : 3, "term" : "SENNA, AYRTON" }, { "count" : 2, "term" : "ANDRETTI, MARIO" }, { "count" : 2, "term" : "FABI, TEO" }, { "count" : 2, "term" : "FRANCE, BILL JR" }, { "count" : 2, "term" : "LUYENDYK, ARIE" }, { "count" : 2, "term" : "ZANARDI, ALEX" }, { "count" : 1, "term" : "ALLEN, WOODY" }, { "count" : 1, "term" : "BARBER, GEORGE" }, { "count" : 1, "term" : "BOURDAIS, SEBASTIEN" }, { "count" : 1, "term" : "BRACK, KENNY" }, { "count" : 1, "term" : "CASTRONEVES, HELIO" }, { "count" : 1, "term" : "CONNER, DENNIS" } ] }, "offset" : "0", "results" : [ { "body" : "Phil Hill, one of the greatest of American auto racers, an introspective and cerebral champion whose celebrated driving career began when he took a neighbor's new Oldsmobile for a spin as a 9-year-old, died Thursday in Monterey, Calif. He was 81 and lived in Santa Monica, Calif., in the same house in which he grew up. His death was confirmed by his", "byline" : "By BRUCE WEBER", "classifiers_facet" : [ "Top/News/Sports", "Top/News/Obituaries", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20080829", "day_of_week_facet" : "Friday", "des_facet" : [ "AUTOMOBILE RACING", "DEATHS (OBITUARIES)" ], "desk_facet" : "Sports Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "363", "lead_paragraph" : "", "material_type_facet" : [ "Obituary", "Biography" ], "nytd_des_facet" : [ "Automobile Racing", "Deaths (Obituaries)" ], "nytd_lead_paragraph" : "Mr. Hill was one of the greatest of American auto racers, an introspective and cerebral champion who led a celebrated driving career.", "nytd_org_facet" : [ "Formula One" ], "nytd_per_facet" : [ "Hill, Phil" ], "nytd_section_facet" : [ "Obituaries", "Sports" ], "nytd_title" : "Phil Hill, a Racing Legend at Odds With the Sport at Times, Is Dead at 81", "org_facet" : [ "FORMULA ONE" ], "page_facet" : "8", "per_facet" : [ "HILL, PHIL" ], "publication_day" : "29", "publication_month" : "08", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/08/29/sports/hill_75757.jpg", "source_facet" : "The New York Times", "title" : "Phil Hill, a Racing Legend at Odds With the Sport at Times, Is Dead at 81", "url" : "http://www.nytimes.com/2008/08/29/sports/othersports/29hill.html", "word_count" : "1159" }, { "author" : "Cathy Horyn is the fashion critic for The New York Times", "body" : "ISTANBUL PARK is not really a park but a three-mile-long race-car track situated in a forlorn area of scrubland and solitary, flag-draped Shell gas stations about 40 miles east of Istanbul, off the main highway to Ankara. A development of pink-stucco villas was encroaching on some old farms. It was a Friday morning in early May, two days before the", "byline" : "By CATHY HORYN", "classifiers_facet" : [ "Top/News/World/Countries and Territories/Turkey", "Top/Features/Travel/Guides/Destinations/Europe/Turkey/Istanbul", "Top/Features/Magazine", "Top/News", "Top/Features/Travel/Guides/Destinations/Europe", "Top/Features/Travel/Guides/Destinations/Europe/Turkey", "Top/News/World/Middle East" ], "date" : "20080727", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Magazine Desk", "fee" : "N", "geo_facet" : [ "ISTANBUL (TURKEY)" ], "large_image" : "Y", "large_image_height" : "396", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_geo_facet" : [ "Istanbul (Turkey)" ], "nytd_lead_paragraph" : "He’s the next big thing in Formula One auto racing. But can he hang on to his innocence in the revved-up whirl of Grand Prix?", "nytd_org_facet" : [ "Formula One", "Bayerische Motorenwerke AG", "Renault SA", "Daimler AG" ], "nytd_per_facet" : [ "Hamilton, Lewis" ], "nytd_section_facet" : [ "Magazine" ], "nytd_title" : "Lewis Hamilton Just Wants to Go Fast", "org_facet" : [ "FORMULA ONE", "BAYERISCHE MOTORENWERKE AG", "RENAULT SA", "DAIMLER AG" ], "page_facet" : "30", "per_facet" : [ "HAMILTON, LEWIS" ], "publication_day" : "27", "publication_month" : "07", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/07/27/magazine/27hamilton-75.jpg", "source_facet" : "The New York Times", "title" : "HE'S THE NEXT BIG THING IN FORMULA ONE AUTO RACING. BUT CAN HE HANG ON TO HIS INNOCENCE IN THE REVVED-UP WHIRL OF GRAND PRIX?", "url" : "http://www.nytimes.com/2008/07/27/magazine/27Hamilton-t.html", "word_count" : "5228" }, { "abstract" : "Danica Patrick becomes first woman to win Indy car race; defeats two-time Indy 500 winner Helio Castroneves by nearly six seconds in Indy Japan 300; achieved celebrity three years ago when she became first woman to lead Indianapolis 500; finished fourth in that race but became phenomenon; companies embraced her willingness to market her good looks, but celebrity brought question of when or if she could win; naysayers chorus had grown increasingly loud as her winless streak wore on; in 2007, she switched to team co-owned by Michael Andretti, former racer who is son of Mario Andretti; photos (M)", "body" : "When a 23-year-old rookie named Danica Patrick became the first woman to lead the Indianapolis 500 three years ago, she raised the tantalizing possibility that in a male-dominated American sport, a woman might for the first time stand in victory lane. Patrick eventually finished fourth in that race, but she quickly became a phenomenon. Companies", "byline" : "By DAVE CALDWELL", "classifiers_facet" : [ "Top/News", "Top/News/Sports", "Top/Classifieds/Job Market/Job Categories/Marketing, Advertising and PR", "Top/News/Front Page", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20080421", "day_of_week_facet" : "Monday", "des_facet" : [ "INDY JAPAN 300", "INDIANAPOLIS 500 (AUTO RACE)", "AUTOMOBILE RACING", "RECORDS AND ACHIEVEMENTS", "ADVERTISING AND MARKETING", "WOMEN" ], "desk_facet" : "Sports Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "622", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobile Racing" ], "nytd_lead_paragraph" : "Danica Patrick became the first woman to win an Indy car race, using successful fuel strategy to capture an IndyCar Series event in Motegi, Japan.", "nytd_per_facet" : [ "Patrick, Danica" ], "nytd_section_facet" : [ "Front Page", "Sports" ], "nytd_title" : "Racing to Victory, and Leaving the Men and the Doubters Behind", "page_facet" : "1", "per_facet" : [ "ANDRETTI, MARIO", "ANDRETTI, MICHAEL", "CASTRONEVES, HELIO", "PATRICK, DANICA" ], "publication_day" : "21", "publication_month" : "04", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/04/20/sports/20patrick_75.jpg", "source_facet" : "The New York Times", "title" : "Racing to Victory, and Leaving the Men and the Doubters Behind", "url" : "http://www.nytimes.com/2008/04/21/sports/othersports/21patrick.html", "word_count" : "1086" }, { "body" : "Few scandals in recent years have provoked as much anger and dismay across Europe as the saga of Max Mosley, the overseer of grand prix motor racing who made tabloid news last weekend in a front-page exposé and accompanying Web video showing him in a sadomasochistic orgy with five supposed prostitutes in a London sex ''dungeon.'' But beyond the", "byline" : "By JOHN F. BURNS", "classifiers_facet" : [ "Top/News", "Top/News/World" ], "date" : "20080407", "day_of_week_facet" : "Monday", "des_facet" : [ "NAZI POLICIES TOWARD JEWS AND MINORITIES", "AUTOMOBILE RACING", "RECORDINGS AND DOWNLOADS (VIDEO)", "PROSTITUTION", "SEX" ], "desk_facet" : "Foreign Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "650", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Nazi Policies Toward Jews and Minorities", "Automobile Racing", "Recordings and Downloads (Video)", "Prostitution", "Sex" ], "nytd_lead_paragraph" : "A London tabloid’s claim that Max Mosley was involved in a sex orgy with Nazi undertones has prompted calls for his resignation. He has refused and is suing the tabloid.", "nytd_org_facet" : [ "Formula One", "Sunday Times", "Times of London" ], "nytd_section_facet" : [ "World" ], "nytd_title" : "Possible Nazi Theme of Grand Prix Boss’s Orgy Draws Calls to Quit", "org_facet" : [ "FORMULA ONE", "SUNDAY TIMES", "TIMES OF LONDON" ], "page_facet" : "6", "publication_day" : "07", "publication_month" : "04", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/04/07/world/07formula.75.jpg", "source_facet" : "The New York Times", "title" : "Possible Nazi Theme of Grand Prix Boss's Orgy Draws Calls to Quit", "url" : "http://www.nytimes.com/2008/04/07/world/europe/07formula.html", "word_count" : "1628" }, { "body" : "HOWARD KROPLICK's fascination for local history has led him into lots of musty library archives, looking for the Long Island that predated suburbia. ''I was especially interested in areas where I lived,'' said Mr. Kroplick, 58, who grew up in East Meadow and now lives with his wife and two daughters in East Hills. ''I loved looking at the pictures", "byline" : "By KARIN LIPSON", "classifiers_facet" : [ "Top/News/New York and Region", "Top/Features/Travel/Guides/Destinations/North America/United States/New York/Long Island", "Top/News/U.S./U.S. States, Territories and Possessions/New York", "Top/Features/Travel/Guides/Destinations/North America", "Top/News/New York and Region/Long Island", "Top/Features/Travel/Guides/Destinations/North America/United States/New York", "Top/Features/Travel/Guides/Destinations/North America/United States" ], "date" : "20080316", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Long Island Weekly Desk", "fee" : "N", "geo_facet" : [ "LONG ISLAND (NY)" ], "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_geo_facet" : [ "Long Island (NY)" ], "nytd_lead_paragraph" : "The Vanderbilt Cup Races, automobile rallies held on Long Island from 1904 to 1910, were celebrated sporting events of their day.", "nytd_section_facet" : [ "New York and Region" ], "nytd_title" : "Long Before Nascar, Dirt-Road Daredevils", "page_facet" : "9", "publication_day" : "16", "publication_month" : "03", "publication_year" : "2008", "source_facet" : "The New York Times", "title" : "Long Before Nascar, Dirt-Road Daredevils", "url" : "http://www.nytimes.com/2008/03/16/nyregion/nyregionspecial2/16bookli.html", "word_count" : "588" }, { "body" : "THE telephone call that would change George Schuster's life and, perhaps, the course of the automobile industry didn't give him much time to prepare. He had barely 12 hours to catch an overnight train from New England so he would be in New York City the next morning, Feb. 12, 1908, for the start of the longest auto race in history: around the", "byline" : "By JERRY GARRETT", "classifiers_facet" : [ "Top/Classifieds/Automobiles" ], "date" : "20080210", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Automobiles", "fee" : "N", "large_image" : "Y", "large_image_height" : "432", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "medium_image" : "Y", "medium_image_height" : "240", "medium_image_url" : "", "medium_image_width" : "337", "multimedia" : [ { "headline" : "No Shoulder Next 22,000 Miles", "summary" : "The 1908 New York to Paris race was one of the earliest international automobile races. The interactive map shows the route taken by the American team as well as the planned route for a commemorative race set to begin in May.", "type" : "Other", "url" : "http://www.nytimes.com/interactive/2008/02/10/automobiles/20080210_GREATRACE_MAP.html" }, { "headline" : "Great Race of 1908: Competitors", "height" : "700", "summary" : "Six cars competed in the first around-the-world race from New York to Paris. Only three made it all the way.", "type" : "Slideshow", "url" : "http://www.nytimes.com/slideshow/2008/02/10/automobiles/0210-RACE-CARS_index.html", "width" : "750" } ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_lead_paragraph" : "Competitors in the first around-the-world race traveled by land and by sea, crossing continents with few good roads and making repairs on the fly.", "nytd_section_facet" : [ "Automobiles" ], "nytd_title" : "New York to Paris the Hard Way, 100 Years Ago", "page_facet" : "1", "publication_day" : "10", "publication_month" : "02", "publication_year" : "2008", "related_multimedia" : "Y", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/02/10/automobiles/75-race-01.jpg", "source_facet" : "The New York Times", "title" : "New York to Paris the Hard Way, 100 Years Ago", "url" : "http://www.nytimes.com/2008/02/10/automobiles/10RACE.html", "word_count" : "1485" }, { "abstract" : "Dakar Rally is canceled because of terrorist threats (S)", "body" : "The Dakar Rally, the motorcycle, car and truck race across the Sahara, was canceled Friday by organizers citing ''direct'' threats of terrorism from a militant group linked to Al Qaeda. The 16-day, 5,760-mile race, called off for the first time in its 30-year history, was to start Saturday in Lisbon, with about 550 competitors. The race route winds", "classifiers_facet" : [ "Top/News/Sports", "Top/Features/Travel/Guides/Destinations/Africa/Senegal/Dakar", "Top/News/World/Countries and Territories/Senegal", "Top/Classifieds/Automobiles/Topics/Wheel Spin", "Top/News/World/Africa", "Top/News", "Top/Features/Travel/Guides/Destinations/Africa/Senegal", "Top/Features/Travel/Guides/Destinations/Africa" ], "date" : "20080105", "day_of_week_facet" : "Saturday", "des_facet" : [ "AUTOMOBILE RACING", "TERRORISM", "DAKAR RALLY" ], "desk_facet" : "Sports Desk", "fee" : "N", "geo_facet" : [ "DAKAR (SENEGAL)", "SAHARA DESERT" ], "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Terrorism", "Dakar Rally" ], "nytd_geo_facet" : [ "Dakar (Senegal)", "Sahara Desert" ], "nytd_lead_paragraph" : "The Dakar Rally, the motorcycle, car and truck race across the Sahara, was canceled Friday by organizers citing “direct” threats of terrorism from a militant group linked to Al Qaeda.", "nytd_org_facet" : [ "Al Qaeda" ], "nytd_section_facet" : [ "Sports" ], "nytd_title" : "Rally Canceled After Terror Threats", "org_facet" : [ "AL QAEDA" ], "page_facet" : "6", "publication_day" : "05", "publication_month" : "01", "publication_year" : "2008", "source_facet" : "The New York Times", "title" : "Rally Canceled After Terror Threats", "url" : "http://www.nytimes.com/2008/01/05/sports/othersports/05autos.html", "word_count" : "196" }, { "abstract" : "Alexander Roy's new book The Driver: My Dangerous Pursuit of Speed and Truth in the Outlaw Racing World describes life as illegal endurance-driver; Roy drove from New York to Los Angeles (Calif) in 31 hours in 2006, largely by evading police and avoiding speed traps; photos (M)", "body" : "The message came across the police scanner in October 2006 as Alexander Roy was driving his 2000 BMW M5 west on Interstate 44 in Oklahoma: ''I have a report of a blue BMW speeding, weaving in and out of traffic and driving recklessly. Be advised.'' Roy said he heard it shortly after he and his co-driver, David Maher, had been exceeding 150 miles an", "byline" : "By DAVID SHAFTEL; Happy Blitt contributed reporting.", "classifiers_facet" : [ "Top/Features/Books", "Top/News/Sports", "Top/Features/Travel/Guides/Destinations/North America/United States/California", "Top/News/U.S./Mid-Atlantic", "Top/Classifieds/Automobiles/Topics/Wheel Spin", "Top/Classifieds/Job Market/Job Categories/Media, Entertainment and Publishing", "Top/News/U.S./West", "Top/Features/Travel/Guides/Destinations/North America/United States/California/Los Angeles", "Top/News/U.S./U.S. States, Territories and Possessions/New York", "Top/News", "Top/News/U.S./U.S. States, Territories and Possessions/California", "Top/Features/Travel/Guides/Destinations/North America", "Top/Features/Travel/Guides/Destinations/North America/United States/New York/New York City", "Top/Features/Travel/Guides/Destinations/North America/United States" ], "date" : "20071017", "day_of_week_facet" : "Wednesday", "des_facet" : [ "SPEED LIMITS AND SPEEDING", "AUTOMOBILES", "BOOKS AND LITERATURE", "ROADS AND TRAFFIC", "AUTOMOBILE RACING" ], "desk_facet" : "Sports Desk", "fee" : "N", "geo_facet" : [ "LOS ANGELES (CALIF)", "NEW YORK CITY" ], "large_image" : "Y", "large_image_height" : "352", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "medium_image" : "Y", "medium_image_height" : "240", "medium_image_url" : "", "medium_image_width" : "337", "nytd_des_facet" : [ "Automobiles", "Roads and Traffic" ], "nytd_lead_paragraph" : "Alexander Roy’s memoir, released on Tuesday, describes a subculture of illegal endurance racing and efforts to break transcontinental records set in the 1970s and 80s.", "nytd_org_facet" : [ "HarperCollins Publishers" ], "nytd_section_facet" : [ "Books", "Sports" ], "nytd_title" : "Tale of Outlaw Racing, With the U.S. as a Course", "org_facet" : [ "HARPERCOLLINS PUBLISHERS" ], "page_facet" : "1", "per_facet" : [ "ROY, ALEXANDER" ], "publication_day" : "17", "publication_month" : "10", "publication_year" : "2007", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2007/10/17/sports/17speed.1.75.jpg", "source_facet" : "The New York Times", "title" : "Tale of Outlaw Racing, With the U.S. as a Course", "url" : "http://www.nytimes.com/2007/10/17/sports/othersports/17speed.html", "word_count" : "1234", "works_mentioned_facet" : [ "DRIVER, THE: MY DANGEROUS PURSUIT OF SPEED AND TRUTH (BOOK)" ] }, { "abstract" : "Hans Ruesch, successful Swiss racecar driver in days of European Grand Prix racing and well-received adventure novelist, dies at age 94 (M)", "body" : "Hans Ruesch, a successful Swiss racecar driver in the years before World War II who later became a writer of well-received novels of adventure, two of which became Hollywood films, died on Monday at his home in Lugano, Switzerland. He was 94. The cause was cancer, his daughter, Vivian Ruesch Mellon, said. Mr. Ruesch was believed to have been one of", "byline" : "By MARGALIT FOX", "classifiers_facet" : [ "Top/Features/Books", "Top/News/Sports", "Top/News/Obituaries", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20070903", "day_of_week_facet" : "Monday", "des_facet" : [ "DEATHS (OBITUARIES)", "BOOKS AND LITERATURE", "AUTOMOBILE RACING", "BIOGRAPHICAL INFORMATION" ], "desk_facet" : "Sports Desk", "fee" : "N", "lead_paragraph" : "", "material_type_facet" : [ "Obituary" ], "nytd_des_facet" : [ "Books and Literature", "Deaths (Obituaries)", "Automobile Racing" ], "nytd_lead_paragraph" : "Mr. Ruesch was a successful Swiss racecar driver in the years before World War II who later became a writer of well-received novels of adventure, two of which became Hollywood films.", "nytd_section_facet" : [ "Obituaries", "Books", "Sports" ], "nytd_title" : "Hans Ruesch, Writer and Grand Prix Winner, Dies at 94", "page_facet" : "5", "per_facet" : [ "RUESCH, HANS" ], "publication_day" : "03", "publication_month" : "09", "publication_year" : "2007", "source_facet" : "The New York Times", "title" : "Hans Ruesch, 94, Writer And Grand Prix Winner", "url" : "http://www.nytimes.com/2007/09/03/sports/03ruesch.html", "word_count" : "432" }, { "abstract" : "Jimmie Johnson wins Sharp Aquos 500 (S)", "body" : "Jimmie Johnson grabbed a victory last night at California Speedway, clinching a spot in Nascar's Chase for the Nextel Cup championship and guaranteeing he will be no worse than tied for the top seed in the 10-race playoff. Johnson dominated the second half of the Sharp Aquos 500, a race that began in bright sunshine with temperatures of more than", "byline" : "By THE ASSOCIATED PRESS", "classifiers_facet" : [ "Top/News", "Top/News/Sports", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "column_facet" : "AUTO RACING ROUNDUP", "date" : "20070903", "day_of_week_facet" : "Monday", "des_facet" : [ "AUTOMOBILE RACING", "SHARP AQUOS 500" ], "desk_facet" : "Sports Desk", "fee" : "N", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobile Racing" ], "nytd_lead_paragraph" : "The driver won a shortened race in Detroit on Sunday, his series-best fifth victory this season and the 12th of his career.", "nytd_section_facet" : [ "Sports" ], "nytd_title" : "Johnson Cruises in California for Fifth Win of Season", "page_facet" : "4", "per_facet" : [ "JOHNSON, JIMMIE" ], "publication_day" : "03", "publication_month" : "09", "publication_year" : "2007", "source_facet" : "The New York Times", "title" : "AUTO RACING ROUNDUP; Johnson Cruises in California for Fifth Win of Season", "url" : "http://www.nytimes.com/2007/09/03/sports/othersports/03autos.html", "word_count" : "721" } ], "tokens" : [ "des_facet:[AUTOMOBILE RACING]", "europe" ], "total" : 126 } </nowiki></pre> 2239 2009-07-23T18:58:19Z DeWitt 2 /* The New York Times Article Search API */ A list of existing JSON serializations of search results. == Google Ajax Search API == Reference http://code.google.com/apis/ajaxsearch/documentation/#API_Overview Query: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton Response: <pre><nowiki>{ "responseData": { "cursor": { "currentPageIndex": 0, "moreResultsUrl": "http:\/\/www.google.com\/search?oe=utf8&ie=utf8&source=uds&start=0&hl=en&q=Paris+Hilton", "pages": [ { "start": "0", "label": 1 }, { "start": "4", "label": 2 }, { "start": "8", "label": 3 }, { "start": "12", "label": 4 }, { "start": "16", "label": 5 }, { "start": "20", "label": 6 }, { "start": "24", "label": 7 }, { "start": "28", "label": 8 } ], "estimatedResultCount": "86700000" }, "results": [ { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.parishilton.com", "titleNoFormatting": "Paris Hilton | The Official Website", "title": "<b>Paris Hilton<\/b> | The Official Website", "url": "http:\/\/www.parishilton.com\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:EgDCCgd54xQJ:www.parishilton.com", "unescapedUrl": "http:\/\/www.parishilton.com\/", "content": "<b>ParisHilton<\/b>.com <b>Paris Hilton<\/b>, Nicky <b>Hilton<\/b> Fashion, Pictures, Apparel, Jewellery , Film, and Fun." }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "en.wikipedia.org", "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia", "title": "<b>Paris Hilton<\/b> - Wikipedia, the free encyclopedia", "url": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:TwrPfhd22hYJ:en.wikipedia.org", "unescapedUrl": "http:\/\/en.wikipedia.org\/wiki\/Paris_Hilton", "content": "<b>Paris<\/b> Whitney <b>Hilton<\/b> (born February 17, 1981) is an American celebutante, television personality, actress, singer and model. <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.imdb.com", "titleNoFormatting": "Paris Hilton", "title": "<b>Paris Hilton<\/b>", "url": "http:\/\/www.imdb.com\/name\/nm0385296\/", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:1i34KkqnsooJ:www.imdb.com", "unescapedUrl": "http:\/\/www.imdb.com\/name\/nm0385296\/", "content": "Socialite <b>Paris Hilton<\/b> was born on February 17, 1981 in New York City... Visit IMDb for Photos, Filmography, Discussions, Bio, News, Awards, Agent, <b>...<\/b>" }, { "GsearchResultClass": "GwebSearch", "visibleUrl": "www.myspace.com", "titleNoFormatting": "MySpace.com - Paris Hilton - 27 - Female - California - www ...", "title": "MySpace.com - <b>Paris Hilton<\/b> - 27 - Female - California - www <b>...<\/b>", "url": "http:\/\/www.myspace.com\/parishilton", "cacheUrl": "http:\/\/www.google.com\/search?q=cache:DTzCq3_Z7C0J:www.myspace.com", "unescapedUrl": "http:\/\/www.myspace.com\/parishilton", "content": "<b>Paris Hilton's<\/b> Latest Blog Entry [Subscribe to this Blog] <b>....<\/b> Guess what <b>Paris<\/b> <b>Hilton<\/b>? I've read and bought that, Weekly In Touch Magazine, yesterday! <b>...<\/b>" } ] }, "responseDetails": null, "responseStatus": 200 }</nowiki></pre> == Microsoft Live Search API 2.0 == Reference http://msdn.microsoft.com/en-us/library/dd250846.aspx <pre><nowiki>{ "SearchResponse":{ "Version":"2.0", "Query":{ "SearchTerms":"testign" }, "Spell":{ "Total":1, "Results":[ { "Value":"testing" } ] }, "Web":{ "Total":5100, "Offset":0, "Results":[ { "Title":"Testign part 2 - Tiernan OTooles Programming Blog", "Description":"If this works, it means nothing really, but i have managed to build a .TEXT blog posting app. could be handy if i move my main blog to .TEXT, which i am thinking about..", "Url":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DisplayUrl":"http:\/\/weblogs.asp.net\/tiernanotoole\/archive\/2004\/09\/24\/233830.aspx", "DateTime":"2008-10-21T05:08:05Z", "Rank":-1.835920 } ] } } }</nowiki></pre> == Yahoo Web Search == Reference http://developer.yahoo.com/search/web/V1/webSearch.html Query: http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2&output=json Response: <pre><nowiki>{ "ResultSet": { "Result": [ { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHg7dmMwF;_ylu=X3oDMTBwOHA5a2tvBGNvbG8DdwRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=1602559ol\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=www.madonna.com\/%26w=madonna%26d=A_opCkfiR2xZ%26icp=1%26.intl=us", "Size": "141748" }, "Title": "Madonna", "Url": "http:\/\/www.madonna.com\/", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAHQ7dmMwF;_ylu=X3oDMTB2cXVjNTM5BGNvbG8DdwRsA1dTMQRwb3MDMQRzZWMDc3IEdnRpZAM-\/SIG=11blgi5po\/EXP=1227726544\/**http%3A\/\/www.madonna.com\/", "DisplayUrl": "www.madonna.com\/", "ModificationDate": 1227427200, "Summary": "Official site of pop diva Madonna, with news, music, media, and fan club." }, { "MimeType": "text\/html", "Cache": { "Url": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIQ7dmMwF;_ylu=X3oDMTBwZG5hOWwzBGNvbG8DdwRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=173hm0meq\/EXP=1227726544\/**http%3A\/\/66.218.69.11\/search\/cache%3Fei=UTF-8%26appid=YahooDemo%26query=madonna%26results=2%26output=json%26u=en.wikipedia.org\/wiki\/Madonna_%2528entertainer%2529%26w=madonna%26d=Hl5LlEfiR2ww%26icp=1%26.intl=us", "Size": "332370" }, "Title": "Madonna (Entertainer) - Wikipedia", "Url": "http:\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ClickUrl": "http:\/\/uk.wrs.yahoo.com\/_ylt=A0Je5VNQTSxJVhUAIA7dmMwF;_ylu=X3oDMTB2ZjQ4dDExBGNvbG8DdwRsA1dTMQRwb3MDMgRzZWMDc3IEdnRpZAM-\/SIG=126n039ja\/EXP=1227726544\/**http%3A\/\/en.wikipedia.org\/wiki\/Madonna_(entertainer)", "DisplayUrl": "en.wikipedia.org\/wiki\/Madonna_(entertainer)", "ModificationDate": 1226995200, "Summary": "Exhaustive bio and discography of Madonna's early life, career, \"Sex\" controversy, electronic club mix phase, and more." } ], "totalResultsReturned": 2, "totalResultsAvailable": 340000000, "moreSearch": "\/WebSearchService\/V1\/webSearch?query=madonna&appid=YahooDemo&region=us", "type": "web", "firstResultPosition": 1 } }</nowiki></pre> == eBay Shopping API Search == Reference http://developer.ebay.com/devzone/shopping/docs/howto/js_shopping/js_searchgs_nv_json/js_searchgs_nv_json.html Query: http://open.api.ebay.com/shopping?appid=MyAppID&version=517&siteid=0&callname=FindItems&QueryKeywords=ipod&responseencoding=JSON&callback=true Response: <pre><nowiki>{ "Ack": "Failure", "Build": "e591_core_Bundled_7560815_R1", "Errors": [ { "ErrorClassification": "RequestError", "ErrorCode": "1.20", "LongMessage": "Application ID invalid.", "SeverityCode": "Error", "ShortMessage": "Application ID invalid." } ], "Timestamp": "2008-11-25T19:44:28.387Z", "Version": "591" }</nowiki></pre> ''[That looks like an error response. Was it supposed to be a list of search results?]'' == VoteReport API Search == Reference: http://highearthorbit.com/votereport-mapping-and-data-feeds/ Query: http://votereport.us/reports.json?q=good&count=2 Response: <pre><nowiki>[ { "report": { "display_text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "rating": null, "name": "Nathan Freitas", "zip": null, "reporter": { "twitter_reporter": { "name": "Nathan Freitas", "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, "text": "Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.", "created_at": "2008-11-15T16:19:07Z", "audio_link": null, "updated_at": "2008-11-15T16:19:16Z", "display_html": "<div class=\"balloon\"><a href=\"http:\/\/twitter.com\/natdefreitas\"><img src=http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg class=\"profile\" target=\"_new\"\/><\/a><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_none.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Nathan Freitas<\/span>: <span class=\"entry-title\">Talking about #votereport on android at #mobilecampnyc3 at 11:30. Just enjoyed good session with nathan from mobilecommons.<\/span><br \/><br \/><div class='whenwhere'>reported <a href=\"http:\/\/twitter.com\/natdefreitas\/statuses\/1007133626\">10 days ago<\/a> <br \/>from Brooklyn, NY<br \/>via Twitter<\/div><\/div><\/div>", "wait_time": null, "source": "TWT", "score": 0, "location": { "location": { "administrative_area": "NY", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -73.971043, 40.675234 ] }, "created_at": "2008-10-30T02:43:27Z", "locality": "Brooklyn", "updated_at": "2008-10-30T02:43:27Z", "filter_list": null, "sub_administrative_area": null, "postal_code": null, "country_code": "US", "address": "Brooklyn, NY, USA", "id": 404 } }, "polling_place": null, "id": 12605, "icon": "http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/61379092\/nfavatar_normal.jpg" } }, { "report": { "display_text": "Telephone report to 208-272-9024 #good", "rating": 100, "name": "Telephone User", "zip": "84105", "reporter": { "phone_reporter": { "name": "Telephone User", "icon": "\/images\/phone_icon.jpg" } }, "text": "Telephone report to 208-272-9024 #good", "created_at": "2008-11-15T05:12:44Z", "audio_link": "http:\/\/calls.votereport.us\/1226725807.587.gsm", "updated_at": "2008-11-15T05:12:44Z", "display_html": "<div class=\"balloon\"><br \/><img src=\"\/images\/phone_icon.jpg\" class=\"profile\" \/><img class=\"rating_icon\" style=\"clear:left;\" src=\"\/images\/rating_good.png\" \/><div class=\"balloon_body\"><span class=\"author\" id=\"screen_name\">Telephone User<\/span>: <span class=\"entry-title\">Telephone report to 208-272-9024 #good<\/span><br \/>0 minute wait time<br \/>Rating: 100<br \/><div class='whenwhere'>reported 10 days ago<br \/>from Salt Lake City, UT 84105<br \/>via Telephone<\/div><\/div><\/div>", "wait_time": 0, "source": "TEL", "score": null, "location": { "location": { "administrative_area": "UT", "geo_source_id": 1, "thoroughfare": null, "point": { "type": "Point", "coordinates": [ -111.8628205, 40.7345053 ] }, "created_at": "2008-11-15T05:12:44Z", "locality": "Salt Lake City", "updated_at": "2008-11-15T05:12:44Z", "filter_list": null, "sub_administrative_area": null, "postal_code": "84105", "country_code": "US", "address": "Salt Lake City, UT 84105, USA", "id": 5986 } }, "polling_place": null, "id": 12599, "icon": "http:\/\/votereport.us\/images\/phone_icon.jpg" } } ]</nowiki></pre> == Twitter Search == Reference: http://apiwiki.twitter.com/Search+API+Documentation Query: http://search.twitter.com/search.json?q=twitter&rpp=2 Response: <pre><nowiki>{ "completed_in": 0.021294, "max_id": 1083593812, "next_page": "?page=2&max_id=1083593812&rpp=2&q=twitter", "page": 1, "query": "twitter", "refresh_url": "?since_id=1083593812&q=twitter", "results": [ { "created_at": "Mon, 29 Dec 2008 07:31:23 +0000", "from_user": "camerontoews", "from_user_id": 2809592, "id": 1083593812, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/68670172/camheadSM_normal.jpg", "text": "Just got back from fry night at the barnes'. I hope nobody ever follows jeremy on twitter! Jeeeeez!", "to_user_id": null }, { "created_at": "Mon, 29 Dec 2008 07:31:15 +0000", "from_user": "erillanos", "from_user_id": 320492, "id": 1083593677, "iso_language_code": "en", "profile_image_url": "http://s3.amazonaws.com/twitter_production/profile_images/66271606/DSCN0703_normal.JPG", "text": "@kiffar dont go doing that now. i know i am super depressed right now to but thats to far. i just drink and sleep and twitter to distract me", "to_user": "kiffar", "to_user_id": 444259 } ], "results_per_page": 2, "since_id": 0 }</nowiki></pre> == The New York Times Article Search API == Reference: http://developer.nytimes.com/docs/article_search_api/ Query: http://api.nytimes.com/svc/search/v1/article?query=(field:)keywords (facet:[value])(¶ms)&api-key=your-API-key Response: <pre><nowiki> { "facets" : { "classifiers_facet" : [ { "count" : 83, "term" : "Top/News" }, { "count" : 74, "term" : "Top/Classifieds/Automobiles/Topics/Wheel Spin" }, { "count" : 69, "term" : "Top/News/Sports" }, { "count" : 18, "term" : "Top/Features/Travel/Guides/Destinations/North America" }, { "count" : 18, "term" : "Top/Features/Travel/Guides/Destinations/North America/United States" }, { "count" : 15, "term" : "Top/Features/Travel/Guides/Destinations/Europe" }, { "count" : 10, "term" : "Top/Classifieds/Automobiles" }, { "count" : 10, "term" : "Top/News/Business" }, { "count" : 6, "term" : "Top/Features/Magazine" }, { "count" : 6, "term" : "Top/Features/Travel/Escapes" }, { "count" : 6, "term" : "Top/Features/Travel/Guides/Destinations/Central and South America" }, { "count" : 6, "term" : "Top/News/World/Europe" }, { "count" : 5, "term" : "Top/Classifieds/Job Market/Job Categories/Fashion, Beauty and Fitness" }, { "count" : 5, "term" : "Top/Classifieds/Job Market/Job Categories/Media, Entertainment and Publishing" }, { "count" : 5, "term" : "Top/News/Obituaries" } ], "des_facet" : [ { "count" : 126, "term" : "AUTOMOBILE RACING" }, { "count" : 22, "term" : "AUTOMOBILES" }, { "count" : 15, "term" : "BIOGRAPHICAL INFORMATION" }, { "count" : 8, "term" : "INDIANAPOLIS 500 (AUTO RACE)" }, { "count" : 8, "term" : "PROFESSIONAL ATHLETICS" }, { "count" : 5, "term" : "ACCIDENTS AND SAFETY" }, { "count" : 4, "term" : "DEATHS (OBITUARIES)" }, { "count" : 4, "term" : "FORMULA ONE GRAND PRIX (AUTO RACE)" }, { "count" : 4, "term" : "MERGERS, ACQUISITIONS AND DIVESTITURES" }, { "count" : 4, "term" : "TELEVISION" }, { "count" : 4, "term" : "TRAVEL AND VACATIONS" }, { "count" : 3, "term" : "APPAREL" }, { "count" : 3, "term" : "FINANCES" }, { "count" : 2, "term" : "ADVERTISING" }, { "count" : 2, "term" : "ADVERTISING AND MARKETING" } ], "geo_facet" : [ { "count" : 5, "term" : "UNITED STATES" }, { "count" : 4, "term" : "BRAZIL" }, { "count" : 4, "term" : "EUROPE" }, { "count" : 4, "term" : "NEW YORK CITY" }, { "count" : 3, "term" : "MONACO" }, { "count" : 2, "term" : "AMERICA" }, { "count" : 2, "term" : "FRANCE" }, { "count" : 2, "term" : "GREAT BRITAIN" }, { "count" : 2, "term" : "INDIANAPOLIS (IND)" }, { "count" : 2, "term" : "INDIANAPOLIS (INDIANA)" }, { "count" : 2, "term" : "JAPAN" }, { "count" : 2, "term" : "LONG ISLAND (NY)" }, { "count" : 2, "term" : "SAHARA DESERT" }, { "count" : 1, "term" : "AFRICA" }, { "count" : 1, "term" : "ALABAMA" } ], "org_facet" : [ { "count" : 12, "term" : "FORMULA ONE" }, { "count" : 5, "term" : "NATIONAL ASSN OF STOCK CAR AUTO RACING" }, { "count" : 4, "term" : "FORD MOTOR CO" }, { "count" : 4, "term" : "INDIANAPOLIS MOTOR SPEEDWAY" }, { "count" : 2, "term" : "CHAMPIONSHIP AUTO RACING TEAMS" }, { "count" : 2, "term" : "ESPN" }, { "count" : 2, "term" : "HONDA MOTOR CO" }, { "count" : 2, "term" : "JAGUAR CARS LTD" }, { "count" : 2, "term" : "JAGUAR PLC" }, { "count" : 2, "term" : "MASERATI SPA" }, { "count" : 2, "term" : "MITSUBISHI MOTORS CORP" }, { "count" : 2, "term" : "PHILIP MORRIS COMPANIES INC" }, { "count" : 2, "term" : "PORSCHE AG" }, { "count" : 1, "term" : "AL QAEDA" }, { "count" : 1, "term" : "ALFA ROMEO OF ITALY" } ], "per_facet" : [ { "count" : 3, "term" : "ANDRETTI, MICHAEL" }, { "count" : 3, "term" : "FITTIPALDI, EMERSON" }, { "count" : 3, "term" : "MANSELL, NIGEL" }, { "count" : 3, "term" : "SENNA, AYRTON" }, { "count" : 2, "term" : "ANDRETTI, MARIO" }, { "count" : 2, "term" : "FABI, TEO" }, { "count" : 2, "term" : "FRANCE, BILL JR" }, { "count" : 2, "term" : "LUYENDYK, ARIE" }, { "count" : 2, "term" : "ZANARDI, ALEX" }, { "count" : 1, "term" : "ALLEN, WOODY" }, { "count" : 1, "term" : "BARBER, GEORGE" }, { "count" : 1, "term" : "BOURDAIS, SEBASTIEN" }, { "count" : 1, "term" : "BRACK, KENNY" }, { "count" : 1, "term" : "CASTRONEVES, HELIO" }, { "count" : 1, "term" : "CONNER, DENNIS" } ] }, "offset" : "0", "results" : [ { "body" : "Phil Hill, one of the greatest of American auto racers, an introspective and cerebral champion whose celebrated driving career began when he took a neighbor's new Oldsmobile for a spin as a 9-year-old, died Thursday in Monterey, Calif. He was 81 and lived in Santa Monica, Calif., in the same house in which he grew up. His death was confirmed by his", "byline" : "By BRUCE WEBER", "classifiers_facet" : [ "Top/News/Sports", "Top/News/Obituaries", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20080829", "day_of_week_facet" : "Friday", "des_facet" : [ "AUTOMOBILE RACING", "DEATHS (OBITUARIES)" ], "desk_facet" : "Sports Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "363", "lead_paragraph" : "", "material_type_facet" : [ "Obituary", "Biography" ], "nytd_des_facet" : [ "Automobile Racing", "Deaths (Obituaries)" ], "nytd_lead_paragraph" : "Mr. Hill was one of the greatest of American auto racers, an introspective and cerebral champion who led a celebrated driving career.", "nytd_org_facet" : [ "Formula One" ], "nytd_per_facet" : [ "Hill, Phil" ], "nytd_section_facet" : [ "Obituaries", "Sports" ], "nytd_title" : "Phil Hill, a Racing Legend at Odds With the Sport at Times, Is Dead at 81", "org_facet" : [ "FORMULA ONE" ], "page_facet" : "8", "per_facet" : [ "HILL, PHIL" ], "publication_day" : "29", "publication_month" : "08", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/08/29/sports/hill_75757.jpg", "source_facet" : "The New York Times", "title" : "Phil Hill, a Racing Legend at Odds With the Sport at Times, Is Dead at 81", "url" : "http://www.nytimes.com/2008/08/29/sports/othersports/29hill.html", "word_count" : "1159" }, { "author" : "Cathy Horyn is the fashion critic for The New York Times", "body" : "ISTANBUL PARK is not really a park but a three-mile-long race-car track situated in a forlorn area of scrubland and solitary, flag-draped Shell gas stations about 40 miles east of Istanbul, off the main highway to Ankara. A development of pink-stucco villas was encroaching on some old farms. It was a Friday morning in early May, two days before the", "byline" : "By CATHY HORYN", "classifiers_facet" : [ "Top/News/World/Countries and Territories/Turkey", "Top/Features/Travel/Guides/Destinations/Europe/Turkey/Istanbul", "Top/Features/Magazine", "Top/News", "Top/Features/Travel/Guides/Destinations/Europe", "Top/Features/Travel/Guides/Destinations/Europe/Turkey", "Top/News/World/Middle East" ], "date" : "20080727", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Magazine Desk", "fee" : "N", "geo_facet" : [ "ISTANBUL (TURKEY)" ], "large_image" : "Y", "large_image_height" : "396", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_geo_facet" : [ "Istanbul (Turkey)" ], "nytd_lead_paragraph" : "He’s the next big thing in Formula One auto racing. But can he hang on to his innocence in the revved-up whirl of Grand Prix?", "nytd_org_facet" : [ "Formula One", "Bayerische Motorenwerke AG", "Renault SA", "Daimler AG" ], "nytd_per_facet" : [ "Hamilton, Lewis" ], "nytd_section_facet" : [ "Magazine" ], "nytd_title" : "Lewis Hamilton Just Wants to Go Fast", "org_facet" : [ "FORMULA ONE", "BAYERISCHE MOTORENWERKE AG", "RENAULT SA", "DAIMLER AG" ], "page_facet" : "30", "per_facet" : [ "HAMILTON, LEWIS" ], "publication_day" : "27", "publication_month" : "07", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/07/27/magazine/27hamilton-75.jpg", "source_facet" : "The New York Times", "title" : "HE'S THE NEXT BIG THING IN FORMULA ONE AUTO RACING. BUT CAN HE HANG ON TO HIS INNOCENCE IN THE REVVED-UP WHIRL OF GRAND PRIX?", "url" : "http://www.nytimes.com/2008/07/27/magazine/27Hamilton-t.html", "word_count" : "5228" }, { "abstract" : "Danica Patrick becomes first woman to win Indy car race; defeats two-time Indy 500 winner Helio Castroneves by nearly six seconds in Indy Japan 300; achieved celebrity three years ago when she became first woman to lead Indianapolis 500; finished fourth in that race but became phenomenon; companies embraced her willingness to market her good looks, but celebrity brought question of when or if she could win; naysayers chorus had grown increasingly loud as her winless streak wore on; in 2007, she switched to team co-owned by Michael Andretti, former racer who is son of Mario Andretti; photos (M)", "body" : "When a 23-year-old rookie named Danica Patrick became the first woman to lead the Indianapolis 500 three years ago, she raised the tantalizing possibility that in a male-dominated American sport, a woman might for the first time stand in victory lane. Patrick eventually finished fourth in that race, but she quickly became a phenomenon. Companies", "byline" : "By DAVE CALDWELL", "classifiers_facet" : [ "Top/News", "Top/News/Sports", "Top/Classifieds/Job Market/Job Categories/Marketing, Advertising and PR", "Top/News/Front Page", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20080421", "day_of_week_facet" : "Monday", "des_facet" : [ "INDY JAPAN 300", "INDIANAPOLIS 500 (AUTO RACE)", "AUTOMOBILE RACING", "RECORDS AND ACHIEVEMENTS", "ADVERTISING AND MARKETING", "WOMEN" ], "desk_facet" : "Sports Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "622", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobile Racing" ], "nytd_lead_paragraph" : "Danica Patrick became the first woman to win an Indy car race, using successful fuel strategy to capture an IndyCar Series event in Motegi, Japan.", "nytd_per_facet" : [ "Patrick, Danica" ], "nytd_section_facet" : [ "Front Page", "Sports" ], "nytd_title" : "Racing to Victory, and Leaving the Men and the Doubters Behind", "page_facet" : "1", "per_facet" : [ "ANDRETTI, MARIO", "ANDRETTI, MICHAEL", "CASTRONEVES, HELIO", "PATRICK, DANICA" ], "publication_day" : "21", "publication_month" : "04", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/04/20/sports/20patrick_75.jpg", "source_facet" : "The New York Times", "title" : "Racing to Victory, and Leaving the Men and the Doubters Behind", "url" : "http://www.nytimes.com/2008/04/21/sports/othersports/21patrick.html", "word_count" : "1086" }, { "body" : "Few scandals in recent years have provoked as much anger and dismay across Europe as the saga of Max Mosley, the overseer of grand prix motor racing who made tabloid news last weekend in a front-page exposé and accompanying Web video showing him in a sadomasochistic orgy with five supposed prostitutes in a London sex ''dungeon.'' But beyond the", "byline" : "By JOHN F. BURNS", "classifiers_facet" : [ "Top/News", "Top/News/World" ], "date" : "20080407", "day_of_week_facet" : "Monday", "des_facet" : [ "NAZI POLICIES TOWARD JEWS AND MINORITIES", "AUTOMOBILE RACING", "RECORDINGS AND DOWNLOADS (VIDEO)", "PROSTITUTION", "SEX" ], "desk_facet" : "Foreign Desk", "fee" : "N", "large_image" : "Y", "large_image_height" : "450", "large_image_url" : "", "large_image_width" : "650", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Nazi Policies Toward Jews and Minorities", "Automobile Racing", "Recordings and Downloads (Video)", "Prostitution", "Sex" ], "nytd_lead_paragraph" : "A London tabloid’s claim that Max Mosley was involved in a sex orgy with Nazi undertones has prompted calls for his resignation. He has refused and is suing the tabloid.", "nytd_org_facet" : [ "Formula One", "Sunday Times", "Times of London" ], "nytd_section_facet" : [ "World" ], "nytd_title" : "Possible Nazi Theme of Grand Prix Boss’s Orgy Draws Calls to Quit", "org_facet" : [ "FORMULA ONE", "SUNDAY TIMES", "TIMES OF LONDON" ], "page_facet" : "6", "publication_day" : "07", "publication_month" : "04", "publication_year" : "2008", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/04/07/world/07formula.75.jpg", "source_facet" : "The New York Times", "title" : "Possible Nazi Theme of Grand Prix Boss's Orgy Draws Calls to Quit", "url" : "http://www.nytimes.com/2008/04/07/world/europe/07formula.html", "word_count" : "1628" }, { "body" : "HOWARD KROPLICK's fascination for local history has led him into lots of musty library archives, looking for the Long Island that predated suburbia. ''I was especially interested in areas where I lived,'' said Mr. Kroplick, 58, who grew up in East Meadow and now lives with his wife and two daughters in East Hills. ''I loved looking at the pictures", "byline" : "By KARIN LIPSON", "classifiers_facet" : [ "Top/News/New York and Region", "Top/Features/Travel/Guides/Destinations/North America/United States/New York/Long Island", "Top/News/U.S./U.S. States, Territories and Possessions/New York", "Top/Features/Travel/Guides/Destinations/North America", "Top/News/New York and Region/Long Island", "Top/Features/Travel/Guides/Destinations/North America/United States/New York", "Top/Features/Travel/Guides/Destinations/North America/United States" ], "date" : "20080316", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Long Island Weekly Desk", "fee" : "N", "geo_facet" : [ "LONG ISLAND (NY)" ], "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_geo_facet" : [ "Long Island (NY)" ], "nytd_lead_paragraph" : "The Vanderbilt Cup Races, automobile rallies held on Long Island from 1904 to 1910, were celebrated sporting events of their day.", "nytd_section_facet" : [ "New York and Region" ], "nytd_title" : "Long Before Nascar, Dirt-Road Daredevils", "page_facet" : "9", "publication_day" : "16", "publication_month" : "03", "publication_year" : "2008", "source_facet" : "The New York Times", "title" : "Long Before Nascar, Dirt-Road Daredevils", "url" : "http://www.nytimes.com/2008/03/16/nyregion/nyregionspecial2/16bookli.html", "word_count" : "588" }, { "body" : "THE telephone call that would change George Schuster's life and, perhaps, the course of the automobile industry didn't give him much time to prepare. He had barely 12 hours to catch an overnight train from New England so he would be in New York City the next morning, Feb. 12, 1908, for the start of the longest auto race in history: around the", "byline" : "By JERRY GARRETT", "classifiers_facet" : [ "Top/Classifieds/Automobiles" ], "date" : "20080210", "day_of_week_facet" : "Sunday", "des_facet" : [ "AUTOMOBILES", "AUTOMOBILE RACING" ], "desk_facet" : "Automobiles", "fee" : "N", "large_image" : "Y", "large_image_height" : "432", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "medium_image" : "Y", "medium_image_height" : "240", "medium_image_url" : "", "medium_image_width" : "337", "multimedia" : [ { "headline" : "No Shoulder Next 22,000 Miles", "summary" : "The 1908 New York to Paris race was one of the earliest international automobile races. The interactive map shows the route taken by the American team as well as the planned route for a commemorative race set to begin in May.", "type" : "Other", "url" : "http://www.nytimes.com/interactive/2008/02/10/automobiles/20080210_GREATRACE_MAP.html" }, { "headline" : "Great Race of 1908: Competitors", "height" : "700", "summary" : "Six cars competed in the first around-the-world race from New York to Paris. Only three made it all the way.", "type" : "Slideshow", "url" : "http://www.nytimes.com/slideshow/2008/02/10/automobiles/0210-RACE-CARS_index.html", "width" : "750" } ], "nytd_des_facet" : [ "Automobiles", "Automobile Racing" ], "nytd_lead_paragraph" : "Competitors in the first around-the-world race traveled by land and by sea, crossing continents with few good roads and making repairs on the fly.", "nytd_section_facet" : [ "Automobiles" ], "nytd_title" : "New York to Paris the Hard Way, 100 Years Ago", "page_facet" : "1", "publication_day" : "10", "publication_month" : "02", "publication_year" : "2008", "related_multimedia" : "Y", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2008/02/10/automobiles/75-race-01.jpg", "source_facet" : "The New York Times", "title" : "New York to Paris the Hard Way, 100 Years Ago", "url" : "http://www.nytimes.com/2008/02/10/automobiles/10RACE.html", "word_count" : "1485" }, { "abstract" : "Dakar Rally is canceled because of terrorist threats (S)", "body" : "The Dakar Rally, the motorcycle, car and truck race across the Sahara, was canceled Friday by organizers citing ''direct'' threats of terrorism from a militant group linked to Al Qaeda. The 16-day, 5,760-mile race, called off for the first time in its 30-year history, was to start Saturday in Lisbon, with about 550 competitors. The race route winds", "classifiers_facet" : [ "Top/News/Sports", "Top/Features/Travel/Guides/Destinations/Africa/Senegal/Dakar", "Top/News/World/Countries and Territories/Senegal", "Top/Classifieds/Automobiles/Topics/Wheel Spin", "Top/News/World/Africa", "Top/News", "Top/Features/Travel/Guides/Destinations/Africa/Senegal", "Top/Features/Travel/Guides/Destinations/Africa" ], "date" : "20080105", "day_of_week_facet" : "Saturday", "des_facet" : [ "AUTOMOBILE RACING", "TERRORISM", "DAKAR RALLY" ], "desk_facet" : "Sports Desk", "fee" : "N", "geo_facet" : [ "DAKAR (SENEGAL)", "SAHARA DESERT" ], "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Terrorism", "Dakar Rally" ], "nytd_geo_facet" : [ "Dakar (Senegal)", "Sahara Desert" ], "nytd_lead_paragraph" : "The Dakar Rally, the motorcycle, car and truck race across the Sahara, was canceled Friday by organizers citing “direct” threats of terrorism from a militant group linked to Al Qaeda.", "nytd_org_facet" : [ "Al Qaeda" ], "nytd_section_facet" : [ "Sports" ], "nytd_title" : "Rally Canceled After Terror Threats", "org_facet" : [ "AL QAEDA" ], "page_facet" : "6", "publication_day" : "05", "publication_month" : "01", "publication_year" : "2008", "source_facet" : "The New York Times", "title" : "Rally Canceled After Terror Threats", "url" : "http://www.nytimes.com/2008/01/05/sports/othersports/05autos.html", "word_count" : "196" }, { "abstract" : "Alexander Roy's new book The Driver: My Dangerous Pursuit of Speed and Truth in the Outlaw Racing World describes life as illegal endurance-driver; Roy drove from New York to Los Angeles (Calif) in 31 hours in 2006, largely by evading police and avoiding speed traps; photos (M)", "body" : "The message came across the police scanner in October 2006 as Alexander Roy was driving his 2000 BMW M5 west on Interstate 44 in Oklahoma: ''I have a report of a blue BMW speeding, weaving in and out of traffic and driving recklessly. Be advised.'' Roy said he heard it shortly after he and his co-driver, David Maher, had been exceeding 150 miles an", "byline" : "By DAVID SHAFTEL; Happy Blitt contributed reporting.", "classifiers_facet" : [ "Top/Features/Books", "Top/News/Sports", "Top/Features/Travel/Guides/Destinations/North America/United States/California", "Top/News/U.S./Mid-Atlantic", "Top/Classifieds/Automobiles/Topics/Wheel Spin", "Top/Classifieds/Job Market/Job Categories/Media, Entertainment and Publishing", "Top/News/U.S./West", "Top/Features/Travel/Guides/Destinations/North America/United States/California/Los Angeles", "Top/News/U.S./U.S. States, Territories and Possessions/New York", "Top/News", "Top/News/U.S./U.S. States, Territories and Possessions/California", "Top/Features/Travel/Guides/Destinations/North America", "Top/Features/Travel/Guides/Destinations/North America/United States/New York/New York City", "Top/Features/Travel/Guides/Destinations/North America/United States" ], "date" : "20071017", "day_of_week_facet" : "Wednesday", "des_facet" : [ "SPEED LIMITS AND SPEEDING", "AUTOMOBILES", "BOOKS AND LITERATURE", "ROADS AND TRAFFIC", "AUTOMOBILE RACING" ], "desk_facet" : "Sports Desk", "fee" : "N", "geo_facet" : [ "LOS ANGELES (CALIF)", "NEW YORK CITY" ], "large_image" : "Y", "large_image_height" : "352", "large_image_url" : "", "large_image_width" : "600", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "medium_image" : "Y", "medium_image_height" : "240", "medium_image_url" : "", "medium_image_width" : "337", "nytd_des_facet" : [ "Automobiles", "Roads and Traffic" ], "nytd_lead_paragraph" : "Alexander Roy’s memoir, released on Tuesday, describes a subculture of illegal endurance racing and efforts to break transcontinental records set in the 1970s and 80s.", "nytd_org_facet" : [ "HarperCollins Publishers" ], "nytd_section_facet" : [ "Books", "Sports" ], "nytd_title" : "Tale of Outlaw Racing, With the U.S. as a Course", "org_facet" : [ "HARPERCOLLINS PUBLISHERS" ], "page_facet" : "1", "per_facet" : [ "ROY, ALEXANDER" ], "publication_day" : "17", "publication_month" : "10", "publication_year" : "2007", "small_image" : "Y", "small_image_height" : "75", "small_image_url" : "http://graphics8.nytimes.com/images/2007/10/17/sports/17speed.1.75.jpg", "source_facet" : "The New York Times", "title" : "Tale of Outlaw Racing, With the U.S. as a Course", "url" : "http://www.nytimes.com/2007/10/17/sports/othersports/17speed.html", "word_count" : "1234", "works_mentioned_facet" : [ "DRIVER, THE: MY DANGEROUS PURSUIT OF SPEED AND TRUTH (BOOK)" ] }, { "abstract" : "Hans Ruesch, successful Swiss racecar driver in days of European Grand Prix racing and well-received adventure novelist, dies at age 94 (M)", "body" : "Hans Ruesch, a successful Swiss racecar driver in the years before World War II who later became a writer of well-received novels of adventure, two of which became Hollywood films, died on Monday at his home in Lugano, Switzerland. He was 94. The cause was cancer, his daughter, Vivian Ruesch Mellon, said. Mr. Ruesch was believed to have been one of", "byline" : "By MARGALIT FOX", "classifiers_facet" : [ "Top/Features/Books", "Top/News/Sports", "Top/News/Obituaries", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "date" : "20070903", "day_of_week_facet" : "Monday", "des_facet" : [ "DEATHS (OBITUARIES)", "BOOKS AND LITERATURE", "AUTOMOBILE RACING", "BIOGRAPHICAL INFORMATION" ], "desk_facet" : "Sports Desk", "fee" : "N", "lead_paragraph" : "", "material_type_facet" : [ "Obituary" ], "nytd_des_facet" : [ "Books and Literature", "Deaths (Obituaries)", "Automobile Racing" ], "nytd_lead_paragraph" : "Mr. Ruesch was a successful Swiss racecar driver in the years before World War II who later became a writer of well-received novels of adventure, two of which became Hollywood films.", "nytd_section_facet" : [ "Obituaries", "Books", "Sports" ], "nytd_title" : "Hans Ruesch, Writer and Grand Prix Winner, Dies at 94", "page_facet" : "5", "per_facet" : [ "RUESCH, HANS" ], "publication_day" : "03", "publication_month" : "09", "publication_year" : "2007", "source_facet" : "The New York Times", "title" : "Hans Ruesch, 94, Writer And Grand Prix Winner", "url" : "http://www.nytimes.com/2007/09/03/sports/03ruesch.html", "word_count" : "432" }, { "abstract" : "Jimmie Johnson wins Sharp Aquos 500 (S)", "body" : "Jimmie Johnson grabbed a victory last night at California Speedway, clinching a spot in Nascar's Chase for the Nextel Cup championship and guaranteeing he will be no worse than tied for the top seed in the 10-race playoff. Johnson dominated the second half of the Sharp Aquos 500, a race that began in bright sunshine with temperatures of more than", "byline" : "By THE ASSOCIATED PRESS", "classifiers_facet" : [ "Top/News", "Top/News/Sports", "Top/Classifieds/Automobiles/Topics/Wheel Spin" ], "column_facet" : "AUTO RACING ROUNDUP", "date" : "20070903", "day_of_week_facet" : "Monday", "des_facet" : [ "AUTOMOBILE RACING", "SHARP AQUOS 500" ], "desk_facet" : "Sports Desk", "fee" : "N", "lead_paragraph" : "", "material_type_facet" : [ "News" ], "nytd_des_facet" : [ "Automobile Racing" ], "nytd_lead_paragraph" : "The driver won a shortened race in Detroit on Sunday, his series-best fifth victory this season and the 12th of his career.", "nytd_section_facet" : [ "Sports" ], "nytd_title" : "Johnson Cruises in California for Fifth Win of Season", "page_facet" : "4", "per_facet" : [ "JOHNSON, JIMMIE" ], "publication_day" : "03", "publication_month" : "09", "publication_year" : "2007", "source_facet" : "The New York Times", "title" : "AUTO RACING ROUNDUP; Johnson Cruises in California for Fifth Win of Season", "url" : "http://www.nytimes.com/2007/09/03/sports/othersports/03autos.html", "word_count" : "721" } ], "tokens" : [ "des_facet:[AUTOMOBILE RACING]", "europe" ], "total" : 126 } </nowiki></pre> == Tony Hammond draft at CrossTech == Reference http://www.crossref.org/CrossTech/2009/07/opensearch_formats_for_review.html and http://nurture.nature.com/opensearch/solar2-json.txt Response: <pre><nowiki>{ "feed": { "title": "cql.keywords adj \"solar eclipse\"", "link": [ { "rel": "self", "href": "...?version=1.1&operation=searchRetrieve&query=cql.keywords%20adj%20%22solar%20eclipse%22&httpAccept=application/json&maximumRecords=2&startIndex=12" }, { "rel": "first", "href": "...?version=1.1&operation=searchRetrieve&query=cql.keywords%20adj%20%22solar%20eclipse%22&httpAccept=application/json&maximumRecords=2&startIndex=1" }, { "rel": "previous", "href": "...?version=1.1&operation=searchRetrieve&query=cql.keywords%20adj%20%22solar%20eclipse%22&httpAccept=application/json&maximumRecords=2&startIndex=11" }, { "rel": "next", "href": "...?version=1.1&operation=searchRetrieve&query=cql.keywords%20adj%20%22solar%20eclipse%22&httpAccept=application/json&maximumRecords=2&startIndex=13" }, { "rel": "last", "href": "...?version=1.1&operation=searchRetrieve&query=cql.keywords%20adj%20%22solar%20eclipse%22&httpAccept=application/json&maximumRecords=2&startIndex=1509" } ], "id": "urn:uuid:a6852153-dc12-4cd9-b3e0-f9ff2ed7f0b3", "author": { "name": "Nature Publishing Group", "uri": "http://www.nature.com", "email": "interfaces@nature.com" }, "updated": "2009-07-23T11:38:08+00:00", "rights": "© 2009 Nature Publication Group", "icon": "http:...", "opensearch:totalResults": 1509, "opensearch:startIndex": 12, "opensearch:itemsPerPage": 2, "opensearch:Query": { "opensearch:role": "request", "opensearch:searchTerms": "cql.keywords adj \"solar eclipse\"" }, "sru:numberOfRecords": 1509, "sru:resultSetId": "a6852153-dc12-4cd9-b3e0-f9ff2ed7f0b3", "dc:publisher": "Nature Publishing Group", "dc:language": "en", "dc:rights": "© 2009 Nature Publication Group", "prism:copyright": "© 2009 Nature Publication Group", "prism:rightsAgent": "permissions@nature.com", "entry": [ { "title": "Chronometry: Effect of the 1999 solar eclipse on atomic clocks", "link": "http://dx.doi.org/10.1038/45442", "id": "doi:10.1038/45442", "updated": "2009-07-23T11:38:08+00:00", "sru:recordSchema": "info:srw/schema/11/pam-v2.1", "sru:recordPacking": "xml", "sru:recordData": { "pam:message": { "pam:article": { "xhtml:head": { "dc:identifier": "doi:10.1038/45442", "dc:title": "Chronometry: Effect of the 1999 solar eclipse on atomic clocks", "dc:creator": [ "Thomas Udem", "Jörg Reichert", "Ronald Holzwarth", "Theodor Hänsch", "Rainer Krämer", "Jörg Hahn", "Jens Hammesfahr" ], "prism:publicationName": "Nature", "prism:issn": "0028-0836", "prism:eIssn": null, "prism:doi": "10.1038/45442", "dc:publisher": null, "prism:publicationDate": "1999-12-16", "prism:volume": "402", "prism:number": "6763", "prism:startingPage": "749", "prism:url": "http://dx.doi.org/10.1038/45442", "prism:copyright": null, "prism:alternateTitle": "nature" } } } }, "sru:recordPosition": 12 }, { "title": "The earliest known solar eclipse record redated", "link": "http://dx.doi.org/10.1038/338238a0", "id": "doi:10.1038/338238a0", "updated": "2009-07-23T11:38:08+00:00", "sru:recordSchema": "info:srw/schema/11/pam-v2.1", "sru:recordPacking": "xml", "sru:recordData": { "pam:message": { "pam:article": { "xhtml:head": { "dc:identifier": "doi:10.1038/338238a0", "dc:title": "The earliest known solar eclipse record redated", "dc:creator": [ "T. de Jong", "W. H. van Soldt" ], "prism:publicationName": "Nature", "prism:issn": "0028-0836", "prism:eIssn": null, "prism:doi": "10.1038/338238a0", "dc:publisher": null, "prism:publicationDate": "1989-03-16", "prism:volume": "338", "prism:number": "6212", "prism:startingPage": "238", "prism:url": "http://dx.doi.org/10.1038/338238a0", "prism:copyright": null, "prism:alternateTitle": "nature" } } } }, "sru:recordPosition": 13 } ] } }</nowiki></pre> Community/Mailing lists 1451 1616 2006-08-09T20:11:13Z DeWitt 2 If you are interested in OpenSearch, then please join the developer mailing list at: : http://lists.opensearch.org/mailman/listinfo/discuss 1695 2006-09-05T14:49:24Z DeWitt 2 If you are interested in OpenSearch, then please join the developer mailing list at: : http://lists.opensearch.org/mailman/listinfo/opensearch-discuss 1707 2006-09-05T17:08:04Z DeWitt 2 If you are interested in OpenSearch, then please join the discussion mailing list at: : http://lists.opensearch.org/mailman/listinfo/opensearch-discuss 1937 2007-09-05T21:16:17Z DeWitt 2 If you are interested in OpenSearch, then please join the discussion mailing list at: : http://groups.google.com/group/opensearch Note that this replaces the [http://lists.opensearch.org/mailman/listinfo/opensearch-discuss old mailing list] ([http://lists.opensearch.org/pipermail/opensearch-discuss/ archives]). Please be sure to update your subscriptions. Community/OpenSearch 2 wishlist 1589 1951 2007-11-27T15:43:11Z DeWitt 2 New page: == Background == As OpenSearch approaches its third anniversary and more and more people have called for the protocol to be formally standardized, this wiki document is a place to collect... == Background == As OpenSearch approaches its third anniversary and more and more people have called for the protocol to be formally standardized, this wiki document is a place to collect the community's input on what should and should not be included in OpenSearch 2. == Keep it == == Change it == == Drop it == == Notes == 2354 2010-02-01T18:42:58Z Edsu 95 /* Change it */ == Background == As OpenSearch approaches its third anniversary and more and more people have called for the protocol to be formally standardized, this wiki document is a place to collect the community's input on what should and should not be included in OpenSearch 2. == Keep it == == Change it == Publish spec as an IETF RFC. == Drop it == == Notes == 3243 2012-11-19T08:10:45Z Hamnis 2245 /* Drop it */ == Background == As OpenSearch approaches its third anniversary and more and more people have called for the protocol to be formally standardized, this wiki document is a place to collect the community's input on what should and should not be included in OpenSearch 2. == Keep it == == Change it == Publish spec as an IETF RFC. == Drop it == Replace Url template with RFC-6570 == Notes == Community/OpenSearch client libraries 1434 1555 2006-08-09T15:36:11Z DeWitt 2 [[Community/OpenSearch client libraries]] moved to [[Community/OpenSearch libraries]] #REDIRECT [[Community/OpenSearch libraries]] 2040 2008-06-15T18:08:08Z Xyzzy 262 Fix double redirect #REDIRECT [[Community/OpenSearch software]] Community/OpenSearch community 1468 1723 2006-09-05T21:03:33Z DeWitt 2 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin 1935 2007-08-11T23:15:49Z DeWitt 2 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension 1946 2007-11-21T15:44:52Z Koen 79 /* Notable contributors to the OpenSearch community */ ==+ Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension 1947 2007-11-21T15:45:04Z Koen 79 /* + Notable contributors to the OpenSearch community */ ==++Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension 1948 2007-11-21T15:45:20Z Koen 79 /* ++Notable contributors to the OpenSearch community */ ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension 1991 2008-03-14T04:43:11Z Stlouisbloggers 226 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension *John Hodge---My Open Id 2130 2008-10-02T12:57:45Z Edsu 95 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor 2245 2009-08-19T07:39:55Z Tonyhammond 719 /* Notable contributors to the OpenSearch community */ ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * Tony Hammond - member of OASIS Search Web Services TC 2246 2009-08-19T07:40:56Z Tonyhammond 719 /* Notable contributors to the OpenSearch community */ ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC 2307 2009-11-05T03:35:33Z Nguyenhuynhut 781 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * Nguyen Huy Nhut simple solutions taipan vietnam - Implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC 2308 2009-11-05T03:44:11Z Nguyenhuynhut 781 contact : nguyenhuynhutsimple@gmail ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * * [[User:Nguyen Huy Nhut simple solutions taipan vietnam |Nguyen Huy Nhut simple solutions taipan vietnam ]]- Implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC 2309 2009-11-05T03:45:35Z Nguyenhuynhut 781 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * * [[User:Nguyen Huy Nhut|Nguyen Huy Nhut simple solutions taipan vietnam ]] -- Implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC 2310 2009-11-05T03:46:08Z Nguyenhuynhut 781 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * [[User:Nguyen Huy Nhut|Nguyen Huy Nhut simple solutions taipan vietnam ]] -- Implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC 2311 2009-11-05T03:47:01Z Nguyenhuynhut 781 ==Notable contributors to the OpenSearch community== Please list your name below if you are an active participant in the OpenSearch community. * [[User:DeWitt|DeWitt Clinton]] -- specification author, opensearch.org maintainer, head cheerleader * [[User:Tesler|Joel Tesler]] -- specification contributor, primary implementor * [[User:Mfagan|Michael Fagan]] -- specification contributor, implementor * [[User:JamesSnell|James Snell]] -- specification contributor * Aaron Suave -- specification contributor * Joe Gregorio -- specification contributor * Chris Fairbanks -- implementor of the WordPress plugin * Andrew Turner -- author of the Geo extension * John Hodge---My Open Id * Ed Summers - implementor * [[User:NguyenHuyNhut|Nguyen Huy Nhut simple solutions taipan vietnam]] -- Implementor * [[User:Tonyhammond|Tony Hammond]] - member of OASIS Search Web Services TC Community/OpenSearch enabled search clients 1428 1534 2006-08-08T22:20:43Z DeWitt 2 [[Community/OpenSearch enabled search clients]] moved to [[Community/OpenSearch search clients]] #REDIRECT [[Community/OpenSearch search clients]] Community/OpenSearch enabled search engines 1427 1530 2006-08-08T22:18:41Z DeWitt 2 [[Community/OpenSearch enabled search engines]] moved to [[Community/OpenSearch search engine directories]] #REDIRECT [[Community/OpenSearch search engine directories]] Community/OpenSearch icons 1443 1583 2006-08-09T17:04:25Z DeWitt 2 == Introduction == The following icons can be used to provide a visual cue of the existence of an OpenSearch search engine. Search clients and browser can use these icons to indicate the presence of an [[Specifications/OpenSearch/1.1#OpenSearch description|OpenSearch description document]]. == Icons == == Download == Download the entire package of OpenSearch icons in various formats and sizes here: : ... == License == The icons are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1592 2006-08-09T17:16:06Z DeWitt 2 /* Icons */ == Introduction == The following icons can be used to provide a visual cue of the existence of an OpenSearch search engine. Search clients and browser can use these icons to indicate the presence of an [[Specifications/OpenSearch/1.1#OpenSearch description|OpenSearch description document]]. == Icons == [[Image:opensearch-icon-128x128.jpg]] [[Image:opensearch-icon-64x64.jpg]] [[Image:opensearch-icon-32x32.jpg]] [[Image:opensearch-icon-16x16.jpg]] == Download == Download the entire package of OpenSearch icons in various formats and sizes here: : ... == License == The icons are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1610 2006-08-09T20:04:23Z DeWitt 2 /* Icons */ == Introduction == The following icons can be used to provide a visual cue of the existence of an OpenSearch search engine. Search clients and browser can use these icons to indicate the presence of an [[Specifications/OpenSearch/1.1#OpenSearch description|OpenSearch description document]]. == Icons == ''Note: Before public release of the site, these need to be cleaned up...'' [[Image:opensearch-icon-128x128.jpg]] [[Image:opensearch-icon-64x64.jpg]] [[Image:opensearch-icon-32x32.jpg]] [[Image:opensearch-icon-16x16.jpg]] == Download == Download the entire package of OpenSearch icons in various formats and sizes here: : ... == License == The icons are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1611 2006-08-09T20:07:07Z DeWitt 2 /* Download */ == Introduction == The following icons can be used to provide a visual cue of the existence of an OpenSearch search engine. Search clients and browser can use these icons to indicate the presence of an [[Specifications/OpenSearch/1.1#OpenSearch description|OpenSearch description document]]. == Icons == ''Note: Before public release of the site, these need to be cleaned up...'' [[Image:opensearch-icon-128x128.jpg]] [[Image:opensearch-icon-64x64.jpg]] [[Image:opensearch-icon-32x32.jpg]] [[Image:opensearch-icon-16x16.jpg]] == Download == Download the entire package of OpenSearch icons in various formats (GIF, PNG, JPEG, SVG) and sizes (128x128, 64x64, 32x32, 16x16) here: : [http://69.55.232.189/downloads/opensearch-icon.tgz opensearch-icon.tgz] (37k) : [http://69.55.232.189/downloads/opensearch-icon.zip opensearch-icon.zip] (40k) == License == The icons are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1698 2006-09-05T15:25:43Z DeWitt 2 == Notice == '''These are not for public release just yet. Please hold off before using them in your application or on your website.''' == Introduction == The following icons can be used to provide a visual cue of the existence of an OpenSearch search engine. Search clients and browser can use these icons to indicate the presence of an [[Specifications/OpenSearch/1.1#OpenSearch description|OpenSearch description document]]. == Icons == [[Image:opensearch-icon-128x128.jpg]] [[Image:opensearch-icon-64x64.jpg]] [[Image:opensearch-icon-32x32.jpg]] [[Image:opensearch-icon-16x16.jpg]] == Download == Download the entire package of OpenSearch icons in various formats (GIF, PNG, JPEG, SVG) and sizes (128x128, 64x64, 32x32, 16x16) here: : [http://www.opensearch.org/downloads/opensearch-icon.tgz opensearch-icon.tgz] (37k) : [http://www.opensearch.org/downloads/opensearch-icon.zip opensearch-icon.zip] (40k) == License == The icons are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. Community/OpenSearch libraries 1462 1672 2006-09-04T15:39:18Z DeWitt 2 [[Community/OpenSearch libraries]] moved to [[Community/OpenSearch software]] #REDIRECT [[Community/OpenSearch software]] Community/OpenSearch search clients 1420 1463 2006-07-27T14:22:31Z DeWitt 2 ==Search aggregators== * [http://a9.com A9.com] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] 1499 2006-08-08T17:27:50Z DeWitt 2 /* Search aggregators */ ==Search aggregators== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] 1533 2006-08-08T22:20:43Z DeWitt 2 [[Community/OpenSearch enabled search clients]] moved to [[Community/OpenSearch search clients]] ==Search aggregators== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] 1665 2006-09-04T03:11:42Z DeWitt 2 ==Search aggregators== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] ==See also== * [[Community/OpenSearch libraries|Programing language and application libraries supporting OpenSearch]] 1673 2006-09-04T15:39:45Z DeWitt 2 ==Search aggregators== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 1706 2006-09-05T17:05:47Z DeWitt 2 /* Search aggregators */ ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] * [http://www.mozilla.com/firefox/ Firefox 2.0] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 1739 2006-09-07T14:40:21Z Mfagan 20 ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 1745 2006-09-07T17:20:23Z DeWitt 2 /* Web browsers */ ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 1882 2006-10-14T16:33:53Z DeWitt 2 /* Search aggregation websites */ ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2262 2009-09-20T20:16:17Z Faw 748 /* Web browsers */ Added Arora. ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2264 2009-09-21T11:57:29Z Boloosou 746 /* Search aggregation websites */ == ==网站搜索聚合 * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] * [http://www.google.com/ Google] * [http://www.baidu.com/ Baidu] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2265 2009-09-21T15:59:39Z DeWitt 2 Reverted edits by [[Special:Contributions/Boloosou|Boloosou]] ([[User talk:Boloosou|Talk]]); changed back to last version by [[User:Faw|Faw]] ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2388 2010-04-13T21:11:30Z Edsu 95 ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2393 2010-04-16T12:35:40Z Dontcallmedom 888 /* Web browsers */ IE instructions for installing opensearch ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2526 2011-05-12T23:04:17Z Xyzzy 262 /* Web browsers */ added IE8+ best practices ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx Staying in control of your default search provider], [http://support.microsoft.com/kb/973764 Requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2527 2011-05-12T23:05:17Z Xyzzy 262 spelling ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2528 2011-05-22T18:54:39Z Xyzzy 262 /* Web browsers */ WhatWG (HTML5) deep link ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] 2529 2011-05-22T18:56:39Z Xyzzy 262 /* See also */ ins ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) 2530 2011-05-22T18:57:14Z Xyzzy 262 /* Web browsers */ del ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) 2531 2011-05-22T19:26:17Z Xyzzy 262 /* See also */ AddSearchProvider API specification ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 2533 2011-05-22T19:30:29Z Xyzzy 262 /* See also */ AddSearchProvider moved to [[Community/OpenSearch_software#See_also]] ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) 2534 2011-05-22T19:44:00Z Xyzzy 262 /* Web browsers */ some details for Chrome / Chromium ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) 2535 2011-05-22T20:08:42Z Xyzzy 262 /* See also */ Link type search on the current W3C HTML5 draft ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] 2536 2011-05-22T20:18:54Z Xyzzy 262 /* See also */ added HTML5 Last Call draft (2011-05) ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] ([http://dev.w3.org/html5/spec-LC/links.html#link-type-search Last Call 2011]) 2621 2011-11-11T20:01:05Z Xyzzy 262 /* See also */ added: W3C VoID note, removed: HTML5 LC ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] * [http://www.w3.org/TR/void/#opensearch Linked Datasets with the VoID Vocabulary] (W3C Interest Group Note, 2011-03) 43590 2013-10-03T14:04:32Z DeWitt 2 ==Search aggregation websites== * [http://a9.com A9.com] * [http://osfeed.com/ OSfeed] * [http://tagjag.com/ TagJag] * [http://keywop.com/ Keywop] ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] * [http://browser.yandex.com Yandex.Browser] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] * [http://www.w3.org/TR/void/#opensearch Linked Datasets with the VoID Vocabulary] (W3C Interest Group Note, 2011-03) 43592 2014-06-01T15:52:33Z DeWitt 2 /* Search aggregation websites */ ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 7]: [http://msdn.microsoft.com/en-us/library/cc848862%28VS.85%29.aspx#usr_addprov user instructions to install an opensearch provider]- also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] * [http://browser.yandex.com Yandex.Browser] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] * [http://www.w3.org/TR/void/#opensearch Linked Datasets with the VoID Vocabulary] (W3C Interest Group Note, 2011-03) 43593 2014-06-01T15:53:27Z DeWitt 2 ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer 10]: Add providers at [http://www.iegallery.com/ IE Gallery] * [http://blogs.msdn.com/b/ie/archive/2010/02/17/search-providers-best-practices-on-setting-the-default.aspx Internet Explorer 8+]: [http://blogs.msdn.com/b/ie/archive/2011/05/12/staying-in-control-of-your-default-search-provider.aspx staying in control of your default search provider], [http://support.microsoft.com/kb/973764 requirements for add-ons] (KB 973764) * [http://www.mozilla.com/firefox/ Firefox 2.0] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] * [http://browser.yandex.com Yandex.Browser] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] * [http://www.w3.org/TR/void/#opensearch Linked Datasets with the VoID Vocabulary] (W3C Interest Group Note, 2011-03) 43594 2014-06-01T15:54:27Z DeWitt 2 ==Web browsers== * [http://www.microsoft.com/windows/ie/ Internet Explorer]: Add providers at [http://www.iegallery.com/ IE Gallery] * [http://www.mozilla.com/firefox/ Firefox] - also support [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] * [http://www.arora-browser.org/ Arora] - also supports [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions Extension] and [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Referrer/1.0 OpenSearch Referrer Extension] * [http://www.google.com/chrome Google Chrome] - [http://www.google.com/chrome/intl/en/webmasters-faq.html#osdd Webmasters FAQ], [http://www.chromium.org/tab-to-search Chromium] * [http://browser.yandex.com Yandex.Browser] ==See also== * [[Community/OpenSearch software|Programing language and application libraries supporting OpenSearch]] * [http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-search Link type search] on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] (roughly HTML5 as of 2011) * [http://www.w3.org/TR/html5/links.html#link-type-search Link type search] on [http://www.w3.org/TR/html5/ W3C HTML5 working draft] * [http://www.w3.org/TR/void/#opensearch Linked Datasets with the VoID Vocabulary] (W3C Interest Group Note, 2011-03) Community/OpenSearch search engine directories 1425 1502 2006-08-08T17:30:30Z DeWitt 2 == Sites that maintain lists of search engines that support OpenSearch == 1503 2006-08-08T17:35:23Z DeWitt 2 /* Sites that maintain lists of search engines that support OpenSearch */ == Lists of search engines that support OpenSearch == * [http://a9.com/-/opensearch/public/osrss RSS feed of A9.com's list of OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) 1504 2006-08-08T17:36:12Z DeWitt 2 /* Lists of search engines that support OpenSearch */ == Lists of search engines that support OpenSearch == * [http://a9.com/-/opensearch/public/osrss A9.com's list of OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser, including OpenSearch engines] 1505 2006-08-08T17:38:27Z DeWitt 2 /* Lists of search engines that support OpenSearch */ == Lists of search engines that support OpenSearch == * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.searchplugins.net/ Searchplugins.net] 1506 2006-08-08T17:42:49Z DeWitt 2 /* Lists of search engines that support OpenSearch */ == Lists of search engines that support OpenSearch == * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.searchplugins.net/ Searchplugins.net] 1507 2006-08-08T17:43:44Z DeWitt 2 /* Lists of search engines that support OpenSearch */ == Lists of search engines that support OpenSearch == * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearch List] * [http://www.searchplugins.net/ Searchplugins.net] 1508 2006-08-08T17:44:59Z DeWitt 2 /* Lists of search engines that support OpenSearch */ The following sites contain lists of search engines that support OpenSearch: * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearch List] * [http://www.searchplugins.net/ Searchplugins.net] 1509 2006-08-08T17:45:16Z DeWitt 2 The following sites contain lists of search engines that support OpenSearch: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearch List] * [http://www.searchplugins.net/ Searchplugins.net] 1510 2006-08-08T17:47:32Z DeWitt 2 The following sites contain lists of search engines that support OpenSearch: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] 1529 2006-08-08T22:18:41Z DeWitt 2 [[Community/OpenSearch enabled search engines]] moved to [[Community/OpenSearch search engine directories]] The following sites contain lists of search engines that support OpenSearch: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's list of open OpenSearch engines, as an RSS feed] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] 1541 2006-08-09T14:37:04Z DeWitt 2 The following sites contain lists of search engines that support OpenSearch: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] 1712 2006-09-05T20:37:53Z GregorRothfuss 23 The following sites contain lists of search engines that support OpenSearch: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1730 2006-09-06T12:14:01Z DeWitt 2 Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1736 2006-09-07T14:10:59Z Mfagan 20 GData moved to a different section Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] =Specifications that build on OpenSearch= * this needs to be split into a new page... * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1738 2006-09-07T14:26:49Z Mfagan 20 added some links, organization Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Lists of search engines that support the description and response === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) === Lists of search engines that support the description === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) =Specifications that build on OpenSearch= * this needs to be split into a new page... * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1740 2006-09-07T14:50:07Z Mfagan 20 +thai search plugins Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Lists of search engines that support the description and response === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) === Lists of search engines that support the description === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] =Specifications that build on OpenSearch= * this needs to be split into a new page... * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1741 2006-09-07T15:39:54Z DeWitt 2 /* Lists of search engines that support the description */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Lists of search engines that support the description and response === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] =Specifications that build on OpenSearch= * this needs to be split into a new page... * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1742 2006-09-07T15:41:29Z DeWitt 2 /* Lists of search engines that support the description and response */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] =Specifications that build on OpenSearch= * this needs to be split into a new page... * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1744 2006-09-07T15:44:29Z DeWitt 2 /* Specifications that build on OpenSearch */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 1751 2006-10-03T14:35:04Z DeWitt 2 /* Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] ** [http://a9.com/-/opensearch/public/osrss A9.com's RSS feed of open OpenSearch engines] ([http://a9.com/-/opensearch/public/osd OpenSearch description document for that feed]) (Ed., these look like they are down.) === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 1889 2006-11-08T15:26:17Z DeWitt 2 A9 seems to have removed their RSS feed of open search columns. Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - part of Mozilla; lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 1891 2006-12-11T22:52:02Z DeWitt 2 Correction, Mycroft is not part of Mozilla. Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2031 2008-06-13T22:46:12Z Squires 303 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2276 2009-10-26T14:13:28Z Beaver 771 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://www.search2.net/ Search2.net] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2277 2009-10-26T14:14:06Z Beaver 771 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2278 2009-10-26T14:14:44Z Beaver 771 /* Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2424 2010-07-15T02:21:21Z Findpdf 955 /* Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] * [http://www.findpdf.us/ findPDF.us] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2427 2010-07-17T07:00:23Z DeWitt 2 Reverted edits by [[Special:Contributions/Findpdf|Findpdf]] ([[User talk:Findpdf|Talk]]); changed back to last version by [[User:Beaver|Beaver]] Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2440 2010-09-01T01:17:17Z Simplify3 982 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 2457 2011-01-07T16:39:19Z Djrobsmith 1074 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 3006 2012-07-21T23:52:01Z Openbdb 1944 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] 9422 2012-12-14T09:57:54Z Huysal 9788 /* See also */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] New Years Eve in istanbul is very common to celecrate. There a few ways to celebrate it Dinner cruise http://www.troublefreeholiday.com 31572 2013-01-10T03:39:18Z Greg.hamamjian 30855 /* Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] * [http://www.elitebuys.net/ elitebuys.net] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] New Years Eve in istanbul is very common to celecrate. There a few ways to celebrate it Dinner cruise http://www.troublefreeholiday.com 31575 2013-01-10T03:42:00Z Greg.hamamjian 30855 /* Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] * [http://www.elitebuys.net/ Elite Buys] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] New Years Eve in istanbul is very common to celecrate. There a few ways to celebrate it Dinner cruise http://www.troublefreeholiday.com 31578 2013-01-10T03:43:12Z Greg.hamamjian 30855 /* Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: */ Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] * [http://www.elitebuys.net/ Elite Buys] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] * [http://www.elitebuys.net/ Elite Buys] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] New Years Eve in istanbul is very common to celecrate. There a few ways to celebrate it Dinner cruise http://www.troublefreeholiday.com 43597 2015-09-21T16:37:44Z DeWitt 2 Hundreds of search engines support OpenSearch. The following sites contain lists of search engines that do: === Directories of search engines that can return syndicated (RSS or Atom) [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch results]]: === * [http://opensearch.a9.com/-/search/moreColumns.jsp A9.com's column chooser] * [http://www.search2.net/ Search2.net] * [http://www.elitebuys.net/ Elite Buys] === Directories of search engines that have public [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description documents]]: === * [http://www.enhanceie.com/IE/SearchBuilder.asp EnhanceIE.com's SearchBuilder] * [http://www.microsoft.com/windows/ie/searchguide/default_new.mspx Microsoft's Internet Explorer Search Guide] * [http://mycroft.mozdev.org/ Mycroft Project] - lists both Sherlock and OpenSearch plugins * [http://www.openbdb.com/ Open Books] * [http://www.opensearchlist.com/index.aspx OpenSearchList.com] * [http://www.searchplugins.net/ Searchplugins.net] * [http://tredosoft.com/internet_explorer_7_search_providers Tredosoft's list of search providers] * [http://www.clinteastman.pwp.blueyonder.co.uk/opensearch/ IE7 Beta 2 Search Providers Profiles] * [http://www.prowebsites.net/Internet_Explorer_7/IE_7_Search_Providers.asp#1 IE 7.0 Beta 2 Search Providers] * [http://www.ae35-unit.dk/iesearch/ IE7.0 Beta 2 search plugins] (Danish) * [http://siit.net/members/art/searchplugins/ Thai Search Plugins] * [http://search.infoweb.net/ InfoWeb Search Directory] * [http://free.naplesplus.us/ Naples Florida Search NAPLESPLUS] * [http://search.webgoblin.co.uk/ WebGoblin - Search Engines with OpenSearch] * [http://www.elitebuys.net/ Elite Buys] === See also === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] Community/OpenSearch software 1424 1487 2006-08-08T16:35:00Z DeWitt 2 == Writing OpenSearch == == Reading OpenSearch * [http://www.textualize.com/opensearch Python library] 1488 2006-08-08T16:35:09Z DeWitt 2 /* Writing OpenSearch */ == Writing OpenSearch == == Reading OpenSearch == * [http://www.textualize.com/opensearch Python library] 1489 2006-08-08T16:37:32Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch == == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] * [http://www.textualize.com/opensearch Python library] 1490 2006-08-08T16:44:00Z DeWitt 2 /* Writing OpenSearch */ == Writing OpenSearch == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://hublog.hubmed.org/archives/001212.html Moveable Type] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] * [http://www.textualize.com/opensearch Python library] 1491 2006-08-08T16:46:26Z DeWitt 2 /* Writing OpenSearch */ == Writing OpenSearch == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] * [http://hublog.hubmed.org/archives/001212.html Moveable Type] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] * [http://www.textualize.com/opensearch Python library] 1492 2006-08-08T16:50:45Z DeWitt 2 /* Writing OpenSearch */ == Writing OpenSearch results with various software == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] * [http://www.textualize.com/opensearch Python library] 1493 2006-08-08T16:51:41Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://www.textualize.com/opensearch Python library] by Robert Sanderson 1494 2006-08-08T16:54:34Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://www.textualize.com/opensearch Python library] by Ed Summers 1495 2006-08-08T17:16:19Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers 1496 2006-08-08T17:19:07Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch Rome plugin] 1497 2006-08-08T17:20:35Z DeWitt 2 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch Rome plugin] 1498 2006-08-08T17:21:14Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch Rome plugin] 1554 2006-08-09T15:36:11Z DeWitt 2 [[Community/OpenSearch client libraries]] moved to [[Community/OpenSearch libraries]] == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch Rome plugin] 1671 2006-09-04T15:39:18Z DeWitt 2 [[Community/OpenSearch libraries]] moved to [[Community/OpenSearch software]] == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator Ruby on Rails] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch Rome plugin] 1737 2006-09-07T14:14:37Z Mfagan 20 == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] 1743 2006-09-07T15:43:17Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1747 2006-09-07T23:16:28Z Kidehen 27 /* Added OpenLink Data Spaces Platform */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1748 2006-09-07T23:18:58Z Kidehen 27 /* Adding OpenLink Virtuoso as OpenSearch compliant Client*/ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1892 2006-12-16T16:23:24Z DeWitt 2 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1893 2006-12-16T16:23:53Z DeWitt 2 == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens (new!) * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1894 2006-12-16T16:53:43Z Mfagan 20 == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens (new!) * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1895 2006-12-16T17:57:38Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens (new!) * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] 1896 2007-01-18T15:34:48Z DeWitt 2 /* Other specifications that use OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens (new!) * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] 1897 2007-01-18T15:36:55Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens (new!) * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] 1898 2007-01-18T15:37:07Z DeWitt 2 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] 1899 2007-01-18T15:38:55Z DeWitt 2 == Writing OpenSearch results with various software == * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 1901 2007-02-02T13:14:10Z DeWitt 2 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] (new!) * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 1904 2007-05-24T14:45:46Z DeWitt 2 == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 1942 2007-11-11T17:25:49Z Arnout 67 added section for contributed OpenSearch description documents, added Mantis == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://meta.wikimedia.org/wiki/OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 1945 2007-11-11T20:13:46Z Arnout 67 /* Writing OpenSearch results with various software */ fixed link to MediaWiki extension == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 1999 2008-04-07T07:04:21Z Nan 253 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 2000 2008-04-07T12:29:37Z Nan 253 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] 2038 2008-06-15T17:22:33Z Xyzzy 262 /* See also */ +feedvalidator == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2077 2008-09-17T08:52:13Z Arnout 67 /* Other specifications that use OpenSearch */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://www.textualize.com/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2214 2009-03-17T13:54:20Z Edsu 95 updated the opensearch python library url == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://python.org/pypi/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2263 2009-09-20T20:20:13Z Faw 748 /* Reading OpenSearch */ Added qopensearch. == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://python.org/pypi/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2355 2010-02-01T20:05:53Z Edsu 95 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2418 2010-06-01T19:10:15Z Daehlerr 927 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2444 2010-09-26T23:39:09Z Clach04 997 Added PyOpenSearch == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2456 2010-12-24T14:21:05Z Davide 1063 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2470 2011-02-22T13:20:31Z Christian Philipp 1115 /* Writing OpenSearch results with various software */ linkfix == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) 2532 2011-05-22T19:29:18Z Xyzzy 262 /* See also */ JS AddSearchProvider == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 2620 2011-11-11T11:55:39Z Cyberworldukltd 1424 /* Reading OpenSearch */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) * [http://www.moovieland.com Open movie Search] by Robero D.Douglass == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 2623 2011-11-16T04:13:02Z Xyzzy 262 Reverted edits by [[Special:Contributions/Cyberworldukltd|Cyberworldukltd]] ([[User talk:Cyberworldukltd|Talk]]); changed back to last version by [[User:Xyzzy|Xyzzy]] == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 2769 2012-03-10T02:18:06Z Karpet 1647 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://search.cpan.org/dist/Search-OpenSearch/ Perl server client for Swish3, Xapian, Lucy, KinoSearch] by Peter Karman * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 2770 2012-03-10T02:19:17Z Karpet 1647 /* Writing OpenSearch results with various software */ == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://search.cpan.org/dist/Search-OpenSearch/ Perl engines for Swish3, Xapian, Lucy, KinoSearch] by Peter Karman * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] 3256 2012-11-26T23:28:01Z Ian.truslove 2260 == Writing OpenSearch results with various software == * [http://dev.alfresco.com/ Alfresco] * [http://drupal.org/project/opensearch Drupal OpenSearch Results] by Robert Douglass * [http://search.cpan.org/dist/Kwiki-OpenSearch-Service/ Kwiki] by Tatsuhiko Miyagawa * [http://search.cpan.org/dist/Search-OpenSearch/ Perl engines for Swish3, Xapian, Lucy, KinoSearch] by Peter Karman * [http://lucene-ws.net/ Lucene] * [http://lucene.apache.org/ Lucene by Apache.org] * [http://lucene.apache.org/nutch/ Nutch] * [http://virtuoso.openlinksw.com/wiki/main/Main/OdsIndex OpenLink Data Spaces] by [http://www.openlinksw.com OpenLink Software] * [http://www.mediawiki.org/wiki/Extension:OpenSearch MediaWiki] by Gregory Szorc * [http://hublog.hubmed.org/archives/001212.html Moveable Type] by Alf Eaton * [http://plone.org/products/plos PLOS (Plone OpenSearch)] (new!) * [http://wiki.rubyonrails.org/rails/pages/SearchGenerator SearchGenerator (Ruby on Rails)] * [http://www.williamsburger.com/wb/archives/opensearch-v-1-1 Wordpress] by Chris Fairbanks * [http://geonetwork-opensource.org/ GeoNetwork opensource geospatial catalog] (new!) * [http://code.google.com/p/pyopensearch/ PyOpenSearch] example Python [http://bitbucket.org/mchaput/whoosh/wiki/Home Whoosh] application with jQuery client == Applications with contributed OpenSearch description documents == These applications don't actively support OpenSearch, but the location of their search result pages can be expressed in an OpenSearch description document: * [[Mantis]] issue tracker == Reading OpenSearch == * [http://drupal.org/project/opensearchclient Drupal client library] by Robert Douglass * [http://drupal.org/project/opensearch_aggregator Drupal OpenSearch Aggregator] by Steven Wittens * [http://search.cpan.org/dist/WWW-OpenSearch/ Perl library] by Tatsuhiko Miyagawa and Brian Cassidy * [http://pear.php.net/package/Services_OpenSearch/docs/0.1.0/Services_OpenSearch/_OpenSearch_Services_OpenSearch-0.1.0_OpenSearch_php.html PHP] Hirose Masaaki * [http://github.com/edsu/opensearch Python library] by Ed Summers * [http://wiki.java.net/bin/view/Javawsxml/OpenSearch ROME plugin] * [http://virtuoso.openlinksw.com/wiki/main/ OpenLink Virtuoso] by [http://www.openlinksw.com OpenLink Software] * [http://incubator.apache.org/abdera/ Apache Abdera] * [http://ojax.sourceforge.net/ OJAX] (new!) * [http://libraryfind.org/ LibraryFind open source metasearch application] (new!) * [http://gitorious.org/qopensearch qopensearch - a set of Qt classes] * [http://www.clarience.com/en-GB/Catalog.aspx/Product/OpenSearch-Client-Library-for-.NET---v1.0/B6FD5C7B-BD79-4052-B2E8-A35D9AC720F9 .NET client library] by [http://www.clarience.com/ Clarience] (new!) * [https://github.com/nsidc/OpenSearchlight OpenSearchlight] - An OpenSearch client in JavaScript == Other specifications that use OpenSearch == * [http://code.google.com/apis/gdata/protocol.html Google's GData API] * [http://www.sixapart.com/developers/product_documentation/vox/open_media_profile.html Six Apart's Open Media Profile] * [http://www.last.fm/api/show?service=272 Last.fm API] == See also == * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * The [http://feedvalidator.org feedvalidator] supports OpenSearch descriptions ([http://feedvalidator.googlecode.com/svn/trunk/feedvalidator/src/feedvalidator/opensearch.py opensearch.py], [http://code.google.com/p/feedvalidator/ project]) * [http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#the-external-interface AddSearchProvider] Javascript API on [http://www.whatwg.org/specs/web-apps/current-work/multipage/ WhatWG HTML living standard] Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft 1 1696 2155 2008-11-19T18:11:21Z Screaminggeek 241 Adding proposal for Advertisement extension from Medio Systems == Notice == {{Draft notice}} == Introduction == The OpenSearch Advertisement Extension allows search engines to include advertisements with search results. ''Example of a search result that includes an advertisement:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> <ad:image ad:id="cprp20" ad:width="170" ad:height="30"> <ad:link href="<nowiki>http://example.com/ads/20_off_coffee.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Cafes Near You</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/coffee/</nowiki>" /> <ad:id>1234567890</ad:id> </ad:advertisement> </feed> == Namespace == The XML namespace of the OpenSearch Advertisement Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following element and sub-elements. === The "advertisement" element === The <code>advertisement</code> element is used to specify an advertisement related to the search results. See further in this document for the specifications of sub-elements. : Requirements: This element may appear zero or more times. ''Examples of <code>advertisement</code> elements:'' <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> <ad:image ad:id="cprp20" ad:width="170" ad:height="30"> <ad:link href="<nowiki>http://example.com/ads/20_off_coffee.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Cafes Near You</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/coffee/</nowiki>" /> <ad:id>1234567890</ad:id> </ad:advertisement> <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">Paris and Nicole: Double Trouble?</ad:title> <ad:subTitle atom:type="TEXT">Read this and more at example.com</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com</ad:displayUrl> <ad:image ad:id="pn200" ad:width="200" ad:height="40"> <ad:link href="<nowiki>http://example.com/ads/paris_nicole.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Celebrity Gossip</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/celebs/</nowiki>" /> <ad:id>1234567891</ad:id> </ad:advertisement> ==== The "callOut" sub-element ==== The <code>callOut</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify a textual marker that identifies this content as an advertisement. : Requirements: This element may appear zero or one time. ''Examples of <code>callOut</code> elements:'' <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:callOut atom:type="TEXT">Sponsored Result</ad:callOut> ==== The "title" sub-element ==== The <code>title</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the title of the advertisement. : Requirements: This element may appear zero or one time. ''Examples of <code>title</code> elements:'' <ad:title atom:type="TEXT">Paris and Nicole: Double Trouble?</ad:title> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> ==== The "subTitle" sub-element ==== The <code>subTitle</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the subtitle text of the advertisement. The subtitle text is positioned underneath the advertisement title. : Requirements: This element may appear zero or one time. ''Examples of <code>subTitle</code> elements:'' <ad:subTitle atom:type="TEXT">Read this and more at example.com</ad:subTitle> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> ==== The "displayUrl" sub-element ==== The <code>displayUrl</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the advertisement domain name or URL. This value need not be a valid URL. Most online advertisements display only a domain name as the <code>displayUrl</code>. The <code>displayUrl</code> text is positioned underneath the advertisement subtitle. : Requirements: This element may appear zero or one time. ''Examples of <code>displayUrl</code> elements:'' <ad:displayUrl atom:type="TEXT">example.com</ad:displayUrl> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> ==== The "image" sub-element ==== The <code>image</code> sub-element is used to specify an image displayed in the advertisement. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>id</td> <td>A unique ID for the image advertisement.</td> </tr> <tr> <td>width</td> <td>The integer width of the image.</td> </tr> <tr> <td>height</td> <td>The integer height of the image.</td> </tr> </table> <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>link</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] used to specify the link to an image to display in the advertisement.</td> </tr> <tr> <td>altText</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the alternate text for the image displayed in the advertisement.</td> </tr> </table> ''Examples of <code>image</code> elements:'' <ad:image ad:id="pn200" ad:width="200" ad:height="200"> <ad:link href="http://example.com/banners/paris_nicole_200px.jpg" /> <ad:altText atom:type="TEXT">Click for Celebrity Gossip</ad:altText> </ad:image> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2161 2008-11-20T16:20:23Z Screaminggeek 241 Updated license section per DeWitt's comments == Notice == {{Draft notice}} == Introduction == The OpenSearch Advertisement Extension allows search engines to include advertisements with search results. ''Example of a search result that includes an advertisement:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> <ad:image ad:id="cprp20" ad:width="170" ad:height="30"> <ad:link href="<nowiki>http://example.com/ads/20_off_coffee.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Cafes Near You</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/coffee/</nowiki>" /> <ad:id>1234567890</ad:id> </ad:advertisement> </feed> == Namespace == The XML namespace of the OpenSearch Advertisement Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following element and sub-elements. === The "advertisement" element === The <code>advertisement</code> element is used to specify an advertisement related to the search results. See further in this document for the specifications of sub-elements. : Requirements: This element may appear zero or more times. ''Examples of <code>advertisement</code> elements:'' <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> <ad:image ad:id="cprp20" ad:width="170" ad:height="30"> <ad:link href="<nowiki>http://example.com/ads/20_off_coffee.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Cafes Near You</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/coffee/</nowiki>" /> <ad:id>1234567890</ad:id> </ad:advertisement> <ad:advertisement> <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:title atom:type="TEXT">Paris and Nicole: Double Trouble?</ad:title> <ad:subTitle atom:type="TEXT">Read this and more at example.com</ad:subTitle> <ad:displayUrl atom:type="TEXT">example.com</ad:displayUrl> <ad:image ad:id="pn200" ad:width="200" ad:height="40"> <ad:link href="<nowiki>http://example.com/ads/paris_nicole.jpg</nowiki>" /> <ad:altText atom:type="TEXT">Click for Celebrity Gossip</ad:altText> </ad:image> <atom:link href="<nowiki>http://example.com/celebs/</nowiki>" /> <ad:id>1234567891</ad:id> </ad:advertisement> ==== The "callOut" sub-element ==== The <code>callOut</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify a textual marker that identifies this content as an advertisement. : Requirements: This element may appear zero or one time. ''Examples of <code>callOut</code> elements:'' <ad:callOut atom:type="TEXT">[Ad]</ad:callOut> <ad:callOut atom:type="TEXT">Sponsored Result</ad:callOut> ==== The "title" sub-element ==== The <code>title</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the title of the advertisement. : Requirements: This element may appear zero or one time. ''Examples of <code>title</code> elements:'' <ad:title atom:type="TEXT">Paris and Nicole: Double Trouble?</ad:title> <ad:title atom:type="TEXT">20% Off Coffee</ad:title> ==== The "subTitle" sub-element ==== The <code>subTitle</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the subtitle text of the advertisement. The subtitle text is positioned underneath the advertisement title. : Requirements: This element may appear zero or one time. ''Examples of <code>subTitle</code> elements:'' <ad:subTitle atom:type="TEXT">Read this and more at example.com</ad:subTitle> <ad:subTitle atom:type="TEXT">Walk in and show us this ad on your phone</ad:subTitle> ==== The "displayUrl" sub-element ==== The <code>displayUrl</code> sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the advertisement domain name or URL. This value need not be a valid URL. Most online advertisements display only a domain name as the <code>displayUrl</code>. The <code>displayUrl</code> text is positioned underneath the advertisement subtitle. : Requirements: This element may appear zero or one time. ''Examples of <code>displayUrl</code> elements:'' <ad:displayUrl atom:type="TEXT">example.com</ad:displayUrl> <ad:displayUrl atom:type="TEXT">example.com/coffee</ad:displayUrl> ==== The "image" sub-element ==== The <code>image</code> sub-element is used to specify an image displayed in the advertisement. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>id</td> <td>A unique ID for the image advertisement.</td> </tr> <tr> <td>width</td> <td>The integer width of the image.</td> </tr> <tr> <td>height</td> <td>The integer height of the image.</td> </tr> </table> <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>link</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] used to specify the link to an image to display in the advertisement.</td> </tr> <tr> <td>altText</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] used to specify the alternate text for the image displayed in the advertisement.</td> </tr> </table> ''Examples of <code>image</code> elements:'' <ad:image ad:id="pn200" ad:width="200" ad:height="200"> <ad:link href="http://example.com/banners/paris_nicole_200px.jpg" /> <ad:altText atom:type="TEXT">Click for Celebrity Gossip</ad:altText> </ad:image> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft 1 1697 2156 2008-11-19T18:22:14Z Screaminggeek 241 Adding proposal for Commerce extension from Medio Systems == Notice == {{Draft notice}} == Introduction == The OpenSearch Commerce Extension allows search engines to include information about previewing and purchasing digital commerce items in search results. ''Example of a search result that includes commerce elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> <com:adultContent>false<com:adultContent> <com:partnerId>1234567</com:partnerId> <com:rating>5.0</com:rating> <com:price value="2" unit="GBP" terms="unlimited"/> <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Commmerce Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/commerce/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following elements. === The "adultContent" element === The <code>adultContent</code> element specifies whether the item contains age-restricted content. The definition of "age-restricted content" is defined within locales and out of scope of this document. : Restrictions: The element value is boolean (true or false). A true value indicates that the item contains age-restricted content. : Requirements: This element may appear zero or one time. ''Examples of <code>adultContent</code> elements:'' <com:adultContent>false<com:adultContent> <com:adultContent>true<com:adultContent> === The "attribution" element === The <code>attribution</code> element specifies a contractually-obligated attribution to be displayed with the digital commerce item. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Required?</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>label</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the label to display alongsite the digital commerce item.</td> </tr> <tr> <td>link</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] that is the link target of the attribution label.</td> </tr> </table> ''Examples of <code>attribution</code> elements:'' <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> <com:attribution> <com:label atom:type="TEXT">Movies by Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> === The "partnerId" element === The <code>partnerId</code> element is used to specify a unique identifier of a browsable or consumable digital commerce item in a partner content catalog. : Restrictions: The element value is a String identifier of the item in a partner content catalog. : Requirements: This element may appear zero or one time. ''Examples of <code>partnerId</code> elements:'' <com:partnerId>1234567</com:partnerId> === The "price" element === The <code>price</code> element specifies the purchase terms, price and currency for a consumable digital commerce item. : Restrictions: The element value is undefined. : Requirements: This element may appear zero or more times. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>value</td> <td>A float indicating the value of the consumable item.</td> </tr> <tr> <td>unit</td> <td>The currency unit of the price.</td> </tr> <tr> <td>terms</td> <td>The terms of use for purchasing the product at this price.</td> </tr> <tr> <td>expiration</td> <td>Expiration information for the purchase.</td> </tr> </table> ''Examples of <code>price</code> elements:'' <com:price value="1.99" unit="USD" terms="Trial" expiration="10 days"/> <com:price value="2" unit="GBP" terms="unlimited"/> === The "rating" element === The <code>rating</code> element specifies a numeric rating for a content item. Rating semantics for digital commerce items are out of scope for this specification. : Restrictions: The element value is a float rating value between 0.0 and 5.0, inclusive. : Requirements: This element may appear zero or one time. ''Examples of <code>rating</code> elements:'' <com:rating>1.5</com:rating> <com:rating>5.0</com:rating> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2162 2008-11-20T16:21:03Z Screaminggeek 241 Updated license section per DeWitt's comments == Notice == {{Draft notice}} == Introduction == The OpenSearch Commerce Extension allows search engines to include information about previewing and purchasing digital commerce items in search results. ''Example of a search result that includes commerce elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> <com:adultContent>false<com:adultContent> <com:partnerId>1234567</com:partnerId> <com:rating>5.0</com:rating> <com:price value="2" unit="GBP" terms="unlimited"/> <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Commmerce Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/commerce/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following elements. === The "adultContent" element === The <code>adultContent</code> element specifies whether the item contains age-restricted content. The definition of "age-restricted content" is defined within locales and out of scope of this document. : Restrictions: The element value is boolean (true or false). A true value indicates that the item contains age-restricted content. : Requirements: This element may appear zero or one time. ''Examples of <code>adultContent</code> elements:'' <com:adultContent>false<com:adultContent> <com:adultContent>true<com:adultContent> === The "attribution" element === The <code>attribution</code> element specifies a contractually-obligated attribution to be displayed with the digital commerce item. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Required?</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>label</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the label to display alongsite the digital commerce item.</td> </tr> <tr> <td>link</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] that is the link target of the attribution label.</td> </tr> </table> ''Examples of <code>attribution</code> elements:'' <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> <com:attribution> <com:label atom:type="TEXT">Movies by Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> === The "partnerId" element === The <code>partnerId</code> element is used to specify a unique identifier of a browsable or consumable digital commerce item in a partner content catalog. : Restrictions: The element value is a String identifier of the item in a partner content catalog. : Requirements: This element may appear zero or one time. ''Examples of <code>partnerId</code> elements:'' <com:partnerId>1234567</com:partnerId> === The "price" element === The <code>price</code> element specifies the purchase terms, price and currency for a consumable digital commerce item. : Restrictions: The element value is undefined. : Requirements: This element may appear zero or more times. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>value</td> <td>A float indicating the value of the consumable item.</td> </tr> <tr> <td>unit</td> <td>The currency unit of the price.</td> </tr> <tr> <td>terms</td> <td>The terms of use for purchasing the product at this price.</td> </tr> <tr> <td>expiration</td> <td>Expiration information for the purchase.</td> </tr> </table> ''Examples of <code>price</code> elements:'' <com:price value="1.99" unit="USD" terms="Trial" expiration="10 days"/> <com:price value="2" unit="GBP" terms="unlimited"/> === The "rating" element === The <code>rating</code> element specifies a numeric rating for a content item. Rating semantics for digital commerce items are out of scope for this specification. : Restrictions: The element value is a float rating value between 0.0 and 5.0, inclusive. : Requirements: This element may appear zero or one time. ''Examples of <code>rating</code> elements:'' <com:rating>1.5</com:rating> <com:rating>5.0</com:rating> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2205 2009-02-25T01:49:36Z Ejohns 578 /* The "price" element */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Commerce Extension allows search engines to include information about previewing and purchasing digital commerce items in search results. ''Example of a search result that includes commerce elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> <com:adultContent>false<com:adultContent> <com:partnerId>1234567</com:partnerId> <com:rating>5.0</com:rating> <com:price value="2" unit="GBP" terms="unlimited"/> <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Commmerce Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/commerce/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following elements. === The "adultContent" element === The <code>adultContent</code> element specifies whether the item contains age-restricted content. The definition of "age-restricted content" is defined within locales and out of scope of this document. : Restrictions: The element value is boolean (true or false). A true value indicates that the item contains age-restricted content. : Requirements: This element may appear zero or one time. ''Examples of <code>adultContent</code> elements:'' <com:adultContent>false<com:adultContent> <com:adultContent>true<com:adultContent> === The "attribution" element === The <code>attribution</code> element specifies a contractually-obligated attribution to be displayed with the digital commerce item. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Required?</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>label</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the label to display alongsite the digital commerce item.</td> </tr> <tr> <td>link</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] that is the link target of the attribution label.</td> </tr> </table> ''Examples of <code>attribution</code> elements:'' <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> <com:attribution> <com:label atom:type="TEXT">Movies by Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> === The "partnerId" element === The <code>partnerId</code> element is used to specify a unique identifier of a browsable or consumable digital commerce item in a partner content catalog. : Restrictions: The element value is a String identifier of the item in a partner content catalog. : Requirements: This element may appear zero or one time. ''Examples of <code>partnerId</code> elements:'' <com:partnerId>1234567</com:partnerId> === The "price" element === The <code>price</code> element specifies the purchase terms, price and currency for a consumable digital commerce item. : Restrictions: The element value is undefined. : Requirements: This element may appear zero or more times. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>value</td> <td>A float indicating the value of the consumable item.</td> </tr> <tr> <td>unit</td> <td>The currency unit of the price.</td> </tr> <tr> <td>quantity_break</td> <td>The minimum quantity at which the price is valid.</td> </tr> <tr> <td>terms</td> <td>The terms of use for purchasing the product at this price.</td> </tr> <tr> <td>expiration</td> <td>Expiration information for the purchase.</td> </tr> </table> ''Examples of <code>price</code> elements:'' <com:price value="1.99" unit="USD" terms="Trial" expiration="10 days"/> <com:price value="2" unit="GBP" terms="unlimited"/> <com:price value="0.24" unit="USD" terms="unlimited" quantity_break="10"> === The "rating" element === The <code>rating</code> element specifies a numeric rating for a content item. Rating semantics for digital commerce items are out of scope for this specification. : Restrictions: The element value is a float rating value between 0.0 and 5.0, inclusive. : Requirements: This element may appear zero or one time. ''Examples of <code>rating</code> elements:'' <com:rating>1.5</com:rating> <com:rating>5.0</com:rating> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2206 2009-02-25T01:50:46Z Ejohns 578 /* The "price" element */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Commerce Extension allows search engines to include information about previewing and purchasing digital commerce items in search results. ''Example of a search result that includes commerce elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> <com:adultContent>false<com:adultContent> <com:partnerId>1234567</com:partnerId> <com:rating>5.0</com:rating> <com:price value="2" unit="GBP" terms="unlimited"/> <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Commmerce Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/commerce/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following elements. === The "adultContent" element === The <code>adultContent</code> element specifies whether the item contains age-restricted content. The definition of "age-restricted content" is defined within locales and out of scope of this document. : Restrictions: The element value is boolean (true or false). A true value indicates that the item contains age-restricted content. : Requirements: This element may appear zero or one time. ''Examples of <code>adultContent</code> elements:'' <com:adultContent>false<com:adultContent> <com:adultContent>true<com:adultContent> === The "attribution" element === The <code>attribution</code> element specifies a contractually-obligated attribution to be displayed with the digital commerce item. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Required?</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>label</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the label to display alongsite the digital commerce item.</td> </tr> <tr> <td>link</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] that is the link target of the attribution label.</td> </tr> </table> ''Examples of <code>attribution</code> elements:'' <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> <com:attribution> <com:label atom:type="TEXT">Movies by Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> === The "partnerId" element === The <code>partnerId</code> element is used to specify a unique identifier of a browsable or consumable digital commerce item in a partner content catalog. : Restrictions: The element value is a String identifier of the item in a partner content catalog. : Requirements: This element may appear zero or one time. ''Examples of <code>partnerId</code> elements:'' <com:partnerId>1234567</com:partnerId> === The "price" element === The <code>price</code> element specifies the purchase terms, price and currency for a consumable digital commerce item. : Restrictions: The element value is undefined. : Requirements: This element may appear zero or more times. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>value</td> <td>A float indicating the value of the consumable item.</td> </tr> <tr> <td>unit</td> <td>The currency unit of the price.</td> </tr> <tr> <td>quantity_break</td> <td>The minimum quantity at which the price is valid.</td> </tr> <tr> <td>terms</td> <td>The terms of use for purchasing the product at this price.</td> </tr> <tr> <td>expiration</td> <td>Expiration information for the purchase.</td> </tr> </table> ''Examples of <code>price</code> elements:'' <com:price value="1.99" unit="USD" terms="Trial" expiration="10 days"/> <com:price value="2" unit="GBP" terms="unlimited"/> <com:price value="0.24" unit="USD" terms="unlimited" quantity_break="10"/> === The "rating" element === The <code>rating</code> element specifies a numeric rating for a content item. Rating semantics for digital commerce items are out of scope for this specification. : Restrictions: The element value is a float rating value between 0.0 and 5.0, inclusive. : Requirements: This element may appear zero or one time. ''Examples of <code>rating</code> elements:'' <com:rating>1.5</com:rating> <com:rating>5.0</com:rating> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2207 2009-02-25T01:53:28Z Ejohns 578 == Notice == {{Draft notice}} == Introduction == The OpenSearch Commerce Extension allows search engines to include information about previewing and purchasing digital commerce items in search results. ''Example of a search result that includes commerce elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> <com:adultContent>false<com:adultContent> <com:partnerId>1234567</com:partnerId> <com:rating>5.0</com:rating> <com:price value="2" unit="GBP" terms="unlimited"/> <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Commmerce Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/commerce/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Advertisement extension introduces the following elements. === The "adultContent" element === The <code>adultContent</code> element specifies whether the item contains age-restricted content. The definition of "age-restricted content" is defined within locales and out of scope of this document. : Restrictions: The element value is boolean (true or false). A true value indicates that the item contains age-restricted content. : Requirements: This element may appear zero or one time. ''Examples of <code>adultContent</code> elements:'' <com:adultContent>false<com:adultContent> <com:adultContent>true<com:adultContent> === The "attribution" element === The <code>attribution</code> element specifies a contractually-obligated attribution to be displayed with the digital commerce item. : Requirements: This element may appear zero or one time. <table border="1"> <tr> <td><b>Sub-element Name</b></td> <td><b>Required?</b></td> <td><b>Sub-element Value</b></td> </tr> <tr> <td>label</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the label to display alongsite the digital commerce item.</td> </tr> <tr> <td>link</td> <td>Yes</td> <td>An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] that is the link target of the attribution label.</td> </tr> </table> ''Examples of <code>attribution</code> elements:'' <com:attribution> <com:label atom:type="TEXT">By Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> <com:attribution> <com:label atom:type="TEXT">Movies by Example.com</com:label> <atom:link href="<nowiki>http://example.com</nowiki>"/> </com:attribution> === The "partnerId" element === The <code>partnerId</code> element is used to specify a unique identifier of a browsable or consumable digital commerce item in a partner content catalog. : Restrictions: The element value is a String identifier of the item in a partner content catalog. : Requirements: This element may appear zero or one time. ''Examples of <code>partnerId</code> elements:'' <com:partnerId>1234567</com:partnerId> === The "price" element === The <code>price</code> element specifies the purchase terms, price and currency for a consumable digital commerce item. : Restrictions: The element value is undefined. : Requirements: This element may appear zero or more times. <table border="1"> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>value</td> <td>A float indicating the value of the consumable item.</td> </tr> <tr> <td>unit</td> <td>The currency unit of the price.</td> </tr> <tr> <td>terms</td> <td>The terms of use for purchasing the product at this price.</td> </tr> <tr> <td>expiration</td> <td>Expiration information for the purchase.</td> </tr> </table> ''Examples of <code>price</code> elements:'' <com:price value="1.99" unit="USD" terms="Trial" expiration="10 days"/> <com:price value="2" unit="GBP" terms="unlimited"/> === The "rating" element === The <code>rating</code> element specifies a numeric rating for a content item. Rating semantics for digital commerce items are out of scope for this specification. : Restrictions: The element value is a float rating value between 0.0 and 5.0, inclusive. : Requirements: This element may appear zero or one time. ''Examples of <code>rating</code> elements:'' <com:rating>1.5</com:rating> <com:rating>5.0</com:rating> == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft 1 1699 2158 2008-11-19T18:40:23Z Screaminggeek 241 Adding proposal for Mobile extension from Medio Systems == Notice == {{Draft notice}} == Introduction == Mobile uses of the Internet differ from PC-based access patterns. The purpose of the OpenSearch Mobile extensions is to provide a standard mechanism for querying mobile-centric and PC-centric data providers and displaying results relevant for mobile subscribers and devices. Mobile search requests include information about the device, operator and subscriber. Mobile search responses include answers, not links. Mobile search results are federated from numerous content sources and presented in categories. ''Example of a search result that includes mobile elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <nowiki><!-- ... --></nowiki> <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:subscriber>2065551212</m:subscriber> </feed> == Namespace == The XML namespace of the OpenSearch Mobile Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/mobile/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Parameters == The OpenSearch Mobile extension introduces the following parameters. === The "userAgent" parameter === Replaced with a string describing the User-Agent of the mobile device for which to target search results. This string is parsed and managed by the search service. If the search request includes the User-Agent as a header, then this parameter should not be included in the URL. If the User-Agent header is not provided, or is the value of a proxy or other intermediate server, then this parameter must be included. When the User-Agent parameter is provided, the search engine may filter or format search results to target the specified mobile device. An identifying substring of the User-Agent may be submitted only when the entire User-Agent is not available. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r%2F08.BD.20I%20MIB%2F2.2.1%20Profile%2FMIDP-2.0%20Configuration%2FCLDC-1.1&format=atom</nowiki> === The "subId" parameter === Replaced with the unique identifier of the subscriber or handset. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&subId={m:subId?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&subId=A12C92JXV558&format=atom</nowiki> === The "mcc" and "mnc" parameters === The mcc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_Country_Code Mobile Country Code (MCC)] of the country, and the mnc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_network_code Mobile Network Code (MNC)]of the operator network of the handset where the search request originated. The MCC and MNC are used in combination to uniquely identify a mobile phone operator within the GSM, CDMA, iDEN and UMTS mobile networks and some satellite mobile networks. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&mcc={m:mcc?}&mnc={m:mnc?}&format=atom</nowiki> ''Example request from a Verizon Wireless handset in the United States:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&mcc=310&mnc=012&format=atom</nowiki> === Optional Parameters === The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. ''Example:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&subId={m:subId?}&mnc={m:mnc?}&mcc={m:mcc?}&format=atom</nowiki> == Atom Extensions == === New Relation Values for Atom Link Elements == To capture link relationships for mobile search results, this extension introduces the following new values of the ''rel'' attribute of the [http://www.atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 Atom Link element]. <table border="1"> <tr> <td><b>rel Attribute Value</b></td> <td><b>Description</b></td> </tr> <tr> <td>next-page</td> <td>The value of the href attribute identifies the next full page of search results. </td> </tr> <tr> <td>page-#</td> <td>The value of the href attribute identifies a target page of search results. (i.e. page-2, page-3, etc.)</td> </tr> <tr> <td>section</td> <td>The value of the href attribute identifies a section of search results. (See below for the definition of "section".)</td> </tr> <tr> <tr> <td>detail</td> <td>The value of the href attribute identifies a page containing details for a single search result. </td> </tr> <tr> <td>spelling</td> <td>The value of the href attribute identifies the first full page of search results for a spell-corrected search query. </td> </tr> </table> == Elements == The OpenSearch Mobile extension introduces the following elements. === The "device" element === The <code>device</code> element is used to describe the mobile device targeted by the search results. : Restrictions: The element value is a String that is the User-Agent provided in the search request, either as a parameter or in the request headers. : Requirements: This element may appear zero or one time. <table> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>make</td> <td>The device make or manufacturer.</td> </tr> <tr> <td>model</td> <td>The model name of the device.</td> </tr> <tr> <td>id</td> <td>The search service's unique identifier for the device.</td> </tr> </table> ''Examples of <code>device</code> elements:'' <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:device m:make="Nokia" m:model="N73" m:id="nokia_n73_ver1">NokiaN73</m:device> === The "subscriber" element === The <code>subscriber</code> element is used to identify the mobile subscriber targeted by the search results. : Restrictions: The element value is a String that is the unique identifier of the subscriber. The alphanumeric format of the identifier varies from operator to operator and is out of scope of this specification. : Requirements: This element may appear zero or one time. ''Examples of <code>subscriber</code> elements:'' <m:subscriber>2065551212</m:subscriber> <m:subscriber>1a854e9c02fd2520</m:subscriber> == Nesting Search Results into Sections using Atom Entries == Mobile search is not desktop web search. Mobile search results are presented in a federated format with search results categorized into sections. A section generally corresponds to a. In OpenSearch Mobile, the relationship between sections and search results is expressed in the following way: * All immediate [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] children of the [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] represent sections of mobile search results. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results contains zero or more immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], each representing an individual browsable or consumable mobile search result related to the section. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing an individual mobile search result contains no child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements]. * All [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.category Atom Category elements] elements defined in an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing a section of mobile search results are inherited by the immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], which represent individual search results related to the section. === Suggested Extensions to an Atom Entry Element for Sections === Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>Extension</b></td> <td><b>Description</b></td> </tr> <tr> <td>totalResults</td> <td>core OpenSearch</td> <td>The total number of mobile search results in this section.</td> </tr> <tr> <td>entry</td> <td>core Atom</td> <td>A mobile search result item related to the section. (One atom:entry element per mobile search result.)</td> </tr> </table> === An Example Atom Entry Element for a Section of Search Results === Here is an example of a section of mobile search results. <atom:entry xs:type="m:sectionEntry" xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"> <atom:category term="local-directory" label="LOCAL_DIRECTORY"/> <atom:title atom:type="TEXT">Local Business</atom:title> <atom:link title="9 Results" rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> <opensearch:totalResults>9</opensearch:totalResults> <atom:entry> <atom:title atom:type="TEXT">Cafe 5ive</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">M & M Associates</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">Simons Espresso Cafe</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> </atom:entry> == Suggested Extensions to an Atom Feed Element for Mobile Search == Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] that represents a feed of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>OpenSearch Extension</b></td> <td><b>Description</b></td> </tr> <tr> <td>device</td> <td>Mobile</td> <td>The device targeted for search results.</td> </tr> <tr> <td>subscriber</td> <td>Mobile</td> <td>The subscriber targeted for search results.</td> </tr> <tr> <td>advertisement</td> <td>Advertisement</td> <td>An advertisement to display with mobile search results. (Multiple instances allowed.)</td> </tr> </table> == Related Extensions == Designers of OpenSearch-compliant mobile search systems should consider supporting these additional extensions: * Advertisement * Commerce * Spelling * Relevance * Suggestions (possibly with alternative output formats) == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2159 2008-11-19T18:44:34Z Screaminggeek 241 Adding links to related extensions == Notice == {{Draft notice}} == Introduction == Mobile uses of the Internet differ from PC-based access patterns. The purpose of the OpenSearch Mobile extensions is to provide a standard mechanism for querying mobile-centric and PC-centric data providers and displaying results relevant for mobile subscribers and devices. Mobile search requests include information about the device, operator and subscriber. Mobile search responses include answers, not links. Mobile search results are federated from numerous content sources and presented in categories. ''Example of a search result that includes mobile elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <nowiki><!-- ... --></nowiki> <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:subscriber>2065551212</m:subscriber> </feed> == Namespace == The XML namespace of the OpenSearch Mobile Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/mobile/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Parameters == The OpenSearch Mobile extension introduces the following parameters. === The "userAgent" parameter === Replaced with a string describing the User-Agent of the mobile device for which to target search results. This string is parsed and managed by the search service. If the search request includes the User-Agent as a header, then this parameter should not be included in the URL. If the User-Agent header is not provided, or is the value of a proxy or other intermediate server, then this parameter must be included. When the User-Agent parameter is provided, the search engine may filter or format search results to target the specified mobile device. An identifying substring of the User-Agent may be submitted only when the entire User-Agent is not available. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r%2F08.BD.20I%20MIB%2F2.2.1%20Profile%2FMIDP-2.0%20Configuration%2FCLDC-1.1&format=atom</nowiki> === The "subId" parameter === Replaced with the unique identifier of the subscriber or handset. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&subId={m:subId?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&subId=A12C92JXV558&format=atom</nowiki> === The "mcc" and "mnc" parameters === The mcc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_Country_Code Mobile Country Code (MCC)] of the country, and the mnc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_network_code Mobile Network Code (MNC)]of the operator network of the handset where the search request originated. The MCC and MNC are used in combination to uniquely identify a mobile phone operator within the GSM, CDMA, iDEN and UMTS mobile networks and some satellite mobile networks. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&mcc={m:mcc?}&mnc={m:mnc?}&format=atom</nowiki> ''Example request from a Verizon Wireless handset in the United States:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&mcc=310&mnc=012&format=atom</nowiki> === Optional Parameters === The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. ''Example:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&subId={m:subId?}&mnc={m:mnc?}&mcc={m:mcc?}&format=atom</nowiki> == Atom Extensions == === New Relation Values for Atom Link Elements === To capture link relationships for mobile search results, this extension introduces the following new values of the ''rel'' attribute of the [http://www.atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 Atom Link element]. <table border="1"> <tr> <td><b>rel Attribute Value</b></td> <td><b>Description</b></td> </tr> <tr> <td>next-page</td> <td>The value of the href attribute identifies the next full page of search results. </td> </tr> <tr> <td>page-#</td> <td>The value of the href attribute identifies a target page of search results. (i.e. page-2, page-3, etc.)</td> </tr> <tr> <td>section</td> <td>The value of the href attribute identifies a section of search results. (See below for the definition of "section".)</td> </tr> <tr> <tr> <td>detail</td> <td>The value of the href attribute identifies a page containing details for a single search result. </td> </tr> <tr> <td>spelling</td> <td>The value of the href attribute identifies the first full page of search results for a spell-corrected search query. </td> </tr> </table> == Elements == The OpenSearch Mobile extension introduces the following elements. === The "device" element === The <code>device</code> element is used to describe the mobile device targeted by the search results. : Restrictions: The element value is a String that is the User-Agent provided in the search request, either as a parameter or in the request headers. : Requirements: This element may appear zero or one time. <table> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>make</td> <td>The device make or manufacturer.</td> </tr> <tr> <td>model</td> <td>The model name of the device.</td> </tr> <tr> <td>id</td> <td>The search service's unique identifier for the device.</td> </tr> </table> ''Examples of <code>device</code> elements:'' <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:device m:make="Nokia" m:model="N73" m:id="nokia_n73_ver1">NokiaN73</m:device> === The "subscriber" element === The <code>subscriber</code> element is used to identify the mobile subscriber targeted by the search results. : Restrictions: The element value is a String that is the unique identifier of the subscriber. The alphanumeric format of the identifier varies from operator to operator and is out of scope of this specification. : Requirements: This element may appear zero or one time. ''Examples of <code>subscriber</code> elements:'' <m:subscriber>2065551212</m:subscriber> <m:subscriber>1a854e9c02fd2520</m:subscriber> == Nesting Search Results into Sections using Atom Entries == Mobile search is not desktop web search. Mobile search results are presented in a federated format with search results categorized into sections. A section generally corresponds to a. In OpenSearch Mobile, the relationship between sections and search results is expressed in the following way: * All immediate [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] children of the [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] represent sections of mobile search results. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results contains zero or more immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], each representing an individual browsable or consumable mobile search result related to the section. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing an individual mobile search result contains no child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements]. * All [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.category Atom Category elements] elements defined in an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing a section of mobile search results are inherited by the immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], which represent individual search results related to the section. === Suggested Extensions to an Atom Entry Element for Sections === Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>Source</b></td> <td><b>Description</b></td> </tr> <tr> <td>totalResults</td> <td>OpenSearch</td> <td>The total number of mobile search results in this section.</td> </tr> <tr> <td>entry</td> <td>Atom</td> <td>A mobile search result item related to the section. (One atom:entry element per mobile search result.)</td> </tr> </table> === An Example Atom Entry Element for a Section of Search Results === Here is an example of a section of mobile search results. <atom:entry xs:type="m:sectionEntry" xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"> <atom:category term="local-directory" label="LOCAL_DIRECTORY"/> <atom:title atom:type="TEXT">Local Business</atom:title> <atom:link title="9 Results" rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> <opensearch:totalResults>9</opensearch:totalResults> <atom:entry> <atom:title atom:type="TEXT">Cafe 5ive</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">M & M Associates</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">Simons Espresso Cafe</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> </atom:entry> == Suggested Extensions to an Atom Feed Element for Mobile Search == Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] that represents a feed of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>OpenSearch Extension</b></td> <td><b>Description</b></td> </tr> <tr> <td>device</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1 Mobile]</td> <td>The device targeted for search results.</td> </tr> <tr> <td>subscriber</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1 Mobile]</td> <td>The subscriber targeted for search results.</td> </tr> <tr> <td>advertisement</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1 Advertisement]</td> <td>An advertisement to display with mobile search results. (Multiple instances allowed.)</td> </tr> </table> == Related Extensions == Designers of OpenSearch-compliant mobile search systems should consider supporting these additional extensions: * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1 Advertisement] * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1 Commerce] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1 Geo] * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1 Spelling] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Relevance/1.0 Relevance] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 Suggestions] (possibly with alternative output formats) == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2163 2008-11-20T16:21:25Z Screaminggeek 241 Updated license section per DeWitt's comments == Notice == {{Draft notice}} == Introduction == Mobile uses of the Internet differ from PC-based access patterns. The purpose of the OpenSearch Mobile extensions is to provide a standard mechanism for querying mobile-centric and PC-centric data providers and displaying results relevant for mobile subscribers and devices. Mobile search requests include information about the device, operator and subscriber. Mobile search responses include answers, not links. Mobile search results are federated from numerous content sources and presented in categories. ''Example of a search result that includes mobile elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <nowiki><!-- ... --></nowiki> <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:subscriber>2065551212</m:subscriber> </feed> == Namespace == The XML namespace of the OpenSearch Mobile Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/mobile/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Parameters == The OpenSearch Mobile extension introduces the following parameters. === The "userAgent" parameter === Replaced with a string describing the User-Agent of the mobile device for which to target search results. This string is parsed and managed by the search service. If the search request includes the User-Agent as a header, then this parameter should not be included in the URL. If the User-Agent header is not provided, or is the value of a proxy or other intermediate server, then this parameter must be included. When the User-Agent parameter is provided, the search engine may filter or format search results to target the specified mobile device. An identifying substring of the User-Agent may be submitted only when the entire User-Agent is not available. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r%2F08.BD.20I%20MIB%2F2.2.1%20Profile%2FMIDP-2.0%20Configuration%2FCLDC-1.1&format=atom</nowiki> === The "subId" parameter === Replaced with the unique identifier of the subscriber or handset. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&subId={m:subId?}&format=atom</nowiki> ''Example request:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&subId=A12C92JXV558&format=atom</nowiki> === The "mcc" and "mnc" parameters === The mcc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_Country_Code Mobile Country Code (MCC)] of the country, and the mnc parameter specifies the [http://en.wikipedia.org/wiki/Mobile_network_code Mobile Network Code (MNC)]of the operator network of the handset where the search request originated. The MCC and MNC are used in combination to uniquely identify a mobile phone operator within the GSM, CDMA, iDEN and UMTS mobile networks and some satellite mobile networks. ''Example URL template:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&mcc={m:mcc?}&mnc={m:mnc?}&format=atom</nowiki> ''Example request from a Verizon Wireless handset in the United States:'' <nowiki>http://example.com/?q=pizza&userAgent=MOT-V3r&mcc=310&mnc=012&format=atom</nowiki> === Optional Parameters === The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. ''Example:'' <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&userAgent={m:userAgent?}&subId={m:subId?}&mnc={m:mnc?}&mcc={m:mcc?}&format=atom</nowiki> == Atom Extensions == === New Relation Values for Atom Link Elements === To capture link relationships for mobile search results, this extension introduces the following new values of the ''rel'' attribute of the [http://www.atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 Atom Link element]. <table border="1"> <tr> <td><b>rel Attribute Value</b></td> <td><b>Description</b></td> </tr> <tr> <td>next-page</td> <td>The value of the href attribute identifies the next full page of search results. </td> </tr> <tr> <td>page-#</td> <td>The value of the href attribute identifies a target page of search results. (i.e. page-2, page-3, etc.)</td> </tr> <tr> <td>section</td> <td>The value of the href attribute identifies a section of search results. (See below for the definition of "section".)</td> </tr> <tr> <tr> <td>detail</td> <td>The value of the href attribute identifies a page containing details for a single search result. </td> </tr> <tr> <td>spelling</td> <td>The value of the href attribute identifies the first full page of search results for a spell-corrected search query. </td> </tr> </table> == Elements == The OpenSearch Mobile extension introduces the following elements. === The "device" element === The <code>device</code> element is used to describe the mobile device targeted by the search results. : Restrictions: The element value is a String that is the User-Agent provided in the search request, either as a parameter or in the request headers. : Requirements: This element may appear zero or one time. <table> <tr> <td><b>Attribute Name</b></td> <td><b>Attribute Value</b></td> </tr> <tr> <td>make</td> <td>The device make or manufacturer.</td> </tr> <tr> <td>model</td> <td>The model name of the device.</td> </tr> <tr> <td>id</td> <td>The search service's unique identifier for the device.</td> </tr> </table> ''Examples of <code>device</code> elements:'' <m:device m:make="Motorola" m:model="V3r" m:id="mot_v3r_ver1">MOT-V3r</m:device> <m:device m:make="Nokia" m:model="N73" m:id="nokia_n73_ver1">NokiaN73</m:device> === The "subscriber" element === The <code>subscriber</code> element is used to identify the mobile subscriber targeted by the search results. : Restrictions: The element value is a String that is the unique identifier of the subscriber. The alphanumeric format of the identifier varies from operator to operator and is out of scope of this specification. : Requirements: This element may appear zero or one time. ''Examples of <code>subscriber</code> elements:'' <m:subscriber>2065551212</m:subscriber> <m:subscriber>1a854e9c02fd2520</m:subscriber> == Nesting Search Results into Sections using Atom Entries == Mobile search is not desktop web search. Mobile search results are presented in a federated format with search results categorized into sections. A section generally corresponds to a. In OpenSearch Mobile, the relationship between sections and search results is expressed in the following way: * All immediate [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] children of the [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] represent sections of mobile search results. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results contains zero or more immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], each representing an individual browsable or consumable mobile search result related to the section. * An [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing an individual mobile search result contains no child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements]. * All [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.category Atom Category elements] elements defined in an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] representing a section of mobile search results are inherited by the immediate child [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry elements], which represent individual search results related to the section. === Suggested Extensions to an Atom Entry Element for Sections === Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry Atom Entry element] that represents a section of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>Source</b></td> <td><b>Description</b></td> </tr> <tr> <td>totalResults</td> <td>OpenSearch</td> <td>The total number of mobile search results in this section.</td> </tr> <tr> <td>entry</td> <td>Atom</td> <td>A mobile search result item related to the section. (One atom:entry element per mobile search result.)</td> </tr> </table> === An Example Atom Entry Element for a Section of Search Results === Here is an example of a section of mobile search results. <atom:entry xs:type="m:sectionEntry" xmlns:xs="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>"> <atom:category term="local-directory" label="LOCAL_DIRECTORY"/> <atom:title atom:type="TEXT">Local Business</atom:title> <atom:link title="9 Results" rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> <opensearch:totalResults>9</opensearch:totalResults> <atom:entry> <atom:title atom:type="TEXT">Cafe 5ive</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">M & M Associates</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> <atom:entry> <atom:title atom:type="TEXT">Simons Espresso Cafe</atom:title> <atom:link rel="self" href="<nowiki>http://example.com/opensearch?q=...</nowiki>"/> </atom:entry> </atom:entry> == Suggested Extensions to an Atom Feed Element for Mobile Search == Here is a list of suggested extension elements for an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#feed.entry Atom Feed element] that represents a feed of mobile search results. <table border="1"> <tr> <td><b>Suggested Element</b></td> <td><b>OpenSearch Extension</b></td> <td><b>Description</b></td> </tr> <tr> <td>device</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1 Mobile]</td> <td>The device targeted for search results.</td> </tr> <tr> <td>subscriber</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1 Mobile]</td> <td>The subscriber targeted for search results.</td> </tr> <tr> <td>advertisement</td> <td>[http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1 Advertisement]</td> <td>An advertisement to display with mobile search results. (Multiple instances allowed.)</td> </tr> </table> == Related Extensions == Designers of OpenSearch-compliant mobile search systems should consider supporting these additional extensions: * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1 Advertisement] * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1 Commerce] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1 Geo] * [http://www.opensearch.org/Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1 Spelling] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Relevance/1.0 Relevance] * [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 Suggestions] (possibly with alternative output formats) == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft 1 1765 2320 2009-11-30T10:51:03Z Tonyhammond 719 OpenSearch SRU extension test test 2321 2009-11-30T10:54:39Z Tonyhammond 719 == Notice == {{Draft notice}} 2322 2009-11-30T10:55:13Z Tonyhammond 719 /* Notice */ == Notice == {{Draft notice}} == Introduction == test test 2323 2009-11-30T11:02:02Z Tonyhammond 719 /* Introduction */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws 2324 2009-11-30T11:03:49Z Tonyhammond 719 == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: This namespace and the corresponding namespace prefix "sru" must be included when the SRU Extension is used in an OpenSearch Description document. 2325 2009-11-30T11:19:47Z Tonyhammond 719 == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "sru" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "queryType" is a string indicating the type of query supplied in the SRU parameter "query" or OpenSearch parameter "searchTerms" - but see below for discussion of the parameter to be used. If "queryType" is omitted, the default is "cql", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "searchTerms" is a reserved value for query type. When "searchTerms" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “cat hat rat”). The server processes the query however it chooses. [Deprecated] The "query" parameter http://example.com/?query={searchTerms}&query={sru:query} (Note: This SRU parameter is provided for completeness only. The SRU parameter "query" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "query" is a query expressed in the query language indicated by ""queryType" (or the default, if "queryType" is omitted). [Deprecated] The "startRecord" parameter http://example.com/?query={searchTerms}&startRecord={sru:startRecord} (Note: This SRU parameter is provided for completeness only. The SRU parameter "startRecord" is a synonym for the OpenSearch parameter "startIndex" which should be used in preference in OpenSearch URL templates.) The SRU parameter "startRecord" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. [Deprecated] The "maximumRecords" parameter http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords} (Note: This SRU parameter is provided for completeness only. The SRU parameter "maximumRecords" is a synonym for the OpenSearch parameter "count" which should be used in preference in OpenSearch URL templates.) The SRU parameter "maximumRecords" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) The "recordPacking" parameter http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking} The SRU parameter "recordPacking" specifies a packing for record data whose value is "string" or "xml" (default is "xml" if omitted). If the value of the parameter is "string", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "xml", then it should embed the XML directly into the response. The "recordSchema" parameter http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema} The SRU parameter "recordSchema" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: http://example.com/?query=dinosaur&recordSchema=mods The "resultSetTTL" parameter http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL} The SRU parameter "resultSetTTL" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) The "sortKeys" parameter http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys} The SRU parameter "sortKeys" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: • path Mandatory. An XPath expression for a tagpath to be used in the sort. • sortSchema Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) • ascending Optional. Boolean, default "true". • caseSensitive Optional. Boolean, default "false". • missingValue Optional. Default is "highValue". See the SRU specification for details on representing the "sortKeys" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: http://example.com/?query=news&sortKeys=title,onix date,onix,,0 This example specifies a sort primarily by "title" from the "onix" schema (with defaults of "ascending", "insensitive" and "highValue" for non-specified sub-parameters), and secondarily by "date" also from the "onix" schema and "insensitive" (with defaults of "ascending" and "highValue" for non-specified sub-parameters). The "stylesheet" parameter http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet} The SRU parameter "stylesheet" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: http://example.com/?query=dinosaur&stylesheet=master.xsl The "rendering" parameter http://example.com/?query={searchTerms}&rendering={sru:rendering} The SRU parameter "rendering" determines whether the stylesheet is to be rendered by the server or client. Its value is "client" or "server". If omitted, the default is "client". Accept Parameters The "httpAccept" parameter http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept} The SRU parameter "httpAccept" may be supplied to indicate the preferred format of the response in lieu of the "Accept" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "application/atom+xml". The default value for the response type is "application/sru+xml", Example: http://example.com/?query=dinosaur&httpAccept=application/atom+xml This example specifies a query ("dinosaur") to an SRU server with results returned as an ATOM document. The "httpAcceptCharset" parameter http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset} The SRU parameter "httpAcceptCharset" may be supplied in lieu of the "Accept-Charset" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The "httpAcceptEncoding" parameter http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding} The SRU parameter "httpAcceptEncoding" may be supplied in lieu of the "Accept-Encoding" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The "httpAcceptLanguage" parameter http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage} The SRU parameter "httpAcceptLanguage" may be supplied in lieu of the "Accept-Language" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The "httpAcceptRanges" parameter http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges} The SRU parameter "httpAcceptRanges" may be supplied in lieu of the "Accept-Ranges" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) Facet Parameters The "facetLimit" parameter http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit} The SRU parameter "facetLimit" specifies the maximum number of counts that should be reported per facet field. The "facetLimit" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: http://example.com/?query=news&facetLimit:dc.subject=100 This example sets the limit to 100 for the dc.subject index. Example: http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100 This example sets the limit to 100 for dc.subject and 10 for all other fields. The "facetStart" parameter http://example.com/?query={searchTerms}&facetStart={sru:facetStart} The SRU parameter "facetStart" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: http://example.com/?query=news&facetStart=10 This example means begin with the 10th count. Example: http://example.com/?query=news&facetStart:dc.subject=10 This example means begin with the 10th count for dc.subject. The "facetSort" parameter http://example.com/?query={searchTerms}&facetSort={sru:facetSort} The SRU parameter "facetSort" is a sort specification for the facet results. It is non-repeatable, and has the following components: • sortBy One of the following: * "recordCount" * "alphanumeric" • order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") • caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: http://example.com/?query=news&facetSort=recordCount Example: http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive The "facetRangeField" parameter http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField} The SRU parameter "facetRangeField" specifies the name of an index to be treated as a range facet. It is repeatable. Example: http://example.com/?query=news&facetRangeField=dateOfPublication The "facetLowValue" parameter http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue} The SRU parameter "facetLowValue" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: http://example.com/?query=news&facetLowValue:dateOfPublication=20010101 The "facetHighValue" parameter http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue} The SRU parameter "facetHighValue" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: http://example.com/?query=news&facetHighValue:dateOfPublication=20040404 The "facetCount" parameter http://example.com/?query={searchTerms}&facetCount={sru:facetCount} The SRU parameter "facetCount" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: http://example.com/?query=news&facetCount:dc.subject=history Extension Parameters The "extension" parameter http://example.com/?query={searchTerms}&x-...={sru:extension} The SRU extension parameter takes on the name of the extension. It must begin with "x-" (lowercase x followed by hyphen). SRU will never include an official extension with a name beginning with "x-", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: http://example.com/?query=news&x-info4-onSearchFail=scan Author Tony Hammond <t.hammond@nature.com> License 2326 2009-11-30T11:39:42Z Tonyhammond 719 == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "sru" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "queryType" is a string indicating the type of query supplied in the SRU parameter "query" or OpenSearch parameter "searchTerms" - but see below for discussion of the parameter to be used. If "queryType" is omitted, the default is "cql", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "searchTerms" is a reserved value for query type. When "searchTerms" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “cat hat rat”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "query" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "query" is a query expressed in the query language indicated by ""queryType" (or the default, if "queryType" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "startRecord" is a synonym for the OpenSearch parameter "startIndex" which should be used in preference in OpenSearch URL templates.) The SRU parameter "startRecord" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "maximumRecords" is a synonym for the OpenSearch parameter "count" which should be used in preference in OpenSearch URL templates.) The SRU parameter "maximumRecords" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "recordPacking" specifies a packing for record data whose value is "string" or "xml" (default is "xml" if omitted). If the value of the parameter is "string", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "xml", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "recordSchema" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "resultSetTTL" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "sortKeys" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * path Mandatory. An XPath expression for a tagpath to be used in the sort. * sortSchema Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * ascending Optional. Boolean, default "true". * caseSensitive Optional. Boolean, default "false". * missingValue Optional. Default is "highValue". See the SRU specification for details on representing the "sortKeys" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "title" from the "onix" schema (with defaults of "ascending", "insensitive" and "highValue" for non-specified sub-parameters), and secondarily by "date" also from the "onix" schema and "insensitive" (with defaults of "ascending" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "stylesheet" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "rendering" determines whether the stylesheet is to be rendered by the server or client. Its value is "client" or "server". If omitted, the default is "client". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "httpAccept" may be supplied to indicate the preferred format of the response in lieu of the "Accept" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "application/atom+xml". The default value for the response type is "application/sru+xml", Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("dinosaur") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "httpAcceptCharset" may be supplied in lieu of the "Accept-Charset" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "httpAcceptEncoding" may be supplied in lieu of the "Accept-Encoding" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "httpAcceptLanguage" may be supplied in lieu of the "Accept-Language" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "httpAcceptRanges" may be supplied in lieu of the "Accept-Ranges" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "facetLimit" specifies the maximum number of counts that should be reported per facet field. The "facetLimit" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the dc.subject index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for dc.subject and 10 for all other fields. The "facetStart" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "facetStart" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for dc.subject. === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "facetSort" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "facetRangeField" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "facetLowValue" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "facetHighValue" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "facetCount" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "x-" (lowercase x followed by hyphen). SRU will never include an official extension with a name beginning with "x-", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == 2327 2009-11-30T11:44:20Z Tonyhammond 719 /* Namespace */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "queryType" is a string indicating the type of query supplied in the SRU parameter "query" or OpenSearch parameter "searchTerms" - but see below for discussion of the parameter to be used. If "queryType" is omitted, the default is "cql", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "searchTerms" is a reserved value for query type. When "searchTerms" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “cat hat rat”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "query" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "query" is a query expressed in the query language indicated by ""queryType" (or the default, if "queryType" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "startRecord" is a synonym for the OpenSearch parameter "startIndex" which should be used in preference in OpenSearch URL templates.) The SRU parameter "startRecord" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "maximumRecords" is a synonym for the OpenSearch parameter "count" which should be used in preference in OpenSearch URL templates.) The SRU parameter "maximumRecords" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "recordPacking" specifies a packing for record data whose value is "string" or "xml" (default is "xml" if omitted). If the value of the parameter is "string", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "xml", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "recordSchema" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "resultSetTTL" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "sortKeys" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * path Mandatory. An XPath expression for a tagpath to be used in the sort. * sortSchema Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * ascending Optional. Boolean, default "true". * caseSensitive Optional. Boolean, default "false". * missingValue Optional. Default is "highValue". See the SRU specification for details on representing the "sortKeys" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "title" from the "onix" schema (with defaults of "ascending", "insensitive" and "highValue" for non-specified sub-parameters), and secondarily by "date" also from the "onix" schema and "insensitive" (with defaults of "ascending" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "stylesheet" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "rendering" determines whether the stylesheet is to be rendered by the server or client. Its value is "client" or "server". If omitted, the default is "client". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "httpAccept" may be supplied to indicate the preferred format of the response in lieu of the "Accept" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "application/atom+xml". The default value for the response type is "application/sru+xml", Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("dinosaur") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "httpAcceptCharset" may be supplied in lieu of the "Accept-Charset" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "httpAcceptEncoding" may be supplied in lieu of the "Accept-Encoding" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "httpAcceptLanguage" may be supplied in lieu of the "Accept-Language" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "httpAcceptRanges" may be supplied in lieu of the "Accept-Ranges" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "facetLimit" specifies the maximum number of counts that should be reported per facet field. The "facetLimit" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the dc.subject index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for dc.subject and 10 for all other fields. The "facetStart" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "facetStart" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for dc.subject. === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "facetSort" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "facetRangeField" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "facetLowValue" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "facetHighValue" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "facetCount" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "x-" (lowercase x followed by hyphen). SRU will never include an official extension with a name beginning with "x-", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == 2328 2009-11-30T11:55:37Z Tonyhammond 719 == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * path Mandatory. An XPath expression for a tagpath to be used in the sort. * sortSchema Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * ascending Optional. Boolean, default "true". * caseSensitive Optional. Boolean, default "false". * missingValue Optional. Default is "highValue". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2329 2009-11-30T12:12:27Z Tonyhammond 719 == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * path ** Mandatory. An XPath expression for a tagpath to be used in the sort. * sortSchema ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * ascending - Optional. Boolean, default "true". * caseSensitive - Optional. Boolean, default "false". * missingValue - Optional. Default is "highValue". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2330 2009-11-30T12:14:03Z Tonyhammond 719 /* The "sortKeys" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path<code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema<code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "true". * <code>caseSensitive</code> ** Optional. Boolean, default "false". * <code>missingValue</code> ** Optional. Default is "highValue". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2331 2009-11-30T12:14:25Z Tonyhammond 719 /* The "sortKeys" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "true". * <code>caseSensitive</code> ** Optional. Boolean, default "false". * <code>missingValue</code> ** Optional. Default is "highValue". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2332 2009-11-30T12:15:13Z Tonyhammond 719 /* The "sortKeys" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * sortBy One of the following: * "recordCount" * "alphanumeric" * order Optional, one of: * "ascending" (default for "alphanumeric") * "descending" (default for "recordCount" or "occurrence") * caseSensitivity Optional, and meaningful only for "alphanumeric". One of: * "caseSensitive" * "caseInsensitive" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2333 2009-11-30T12:18:30Z Tonyhammond 719 /* The "facetSort" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2334 2009-11-30T12:19:57Z Tonyhammond 719 /* The "query" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2335 2009-11-30T12:20:13Z Tonyhammond 719 /* The "startRecord" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> (Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.) The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2336 2009-11-30T12:20:27Z Tonyhammond 719 /* The "maximumRecords" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "searchTerms" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2337 2009-11-30T12:21:32Z Tonyhammond 719 /* The "query" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords<c/ode>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2338 2009-11-30T12:21:48Z Tonyhammond 719 /* The "maximumRecords" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "sortKeys" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2339 2009-11-30T12:22:15Z Tonyhammond 719 /* The "sortKeys" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License. 2340 2009-11-30T12:24:13Z Tonyhammond 719 /* License */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the [Creative Commons Attribution-ShareAlike 2.5 License http://creativecommons.org/licenses/by-sa/2.5/]. 2341 2009-11-30T12:24:44Z Tonyhammond 719 /* License */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # SRU Home Page: http://www.loc.gov/standards/sru/ # SRU 1.2 Specs (Stable): http://www.loc.gov/standards/sru/specs/ # SRU 2.0 Specs (Public Drafts): http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 2342 2009-11-30T12:34:13Z Tonyhammond 719 /* Introduction */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # [http://www.loc.gov/standards/sru/ SRU Home Page] # [http://www.loc.gov/standards/sru/specs/ SRU 1.2 Specs (Stable)] # [http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws SRU 2.0 Specs (Public Drafts)] == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 2423 2010-07-14T20:52:17Z 18GERS6NCH5CARE3575 954 /* The "sortKeys" parameter */ == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # [http://www.loc.gov/standards/sru/ SRU Home Page] # [http://www.loc.gov/standards/sru/specs/ SRU 1.2 Specs (Stable)] # [http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws SRU 2.0 Specs (Public Drafts)] == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Copyright:Gerson Chicareli 2010 Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 2426 2010-07-17T06:59:59Z DeWitt 2 Reverted edits by [[Special:Contributions/18GERS6NCH5CARE3575|18GERS6NCH5CARE3575]] ([[User talk:18GERS6NCH5CARE3575|Talk]]); changed back to last version by [[User:Tonyhammond|Tonyhammond]] == Notice == {{Draft notice}} == Introduction == This OpenSearch SRU Extension allows SRU (Search and Retrieval via URL) queries to be used within OpenSearch contexts. It makes the full SRU request parameter set available to OpenSearch implementations. This SRU Extension is aligned with the SRU 2.0 specification. For further information on SRU see: # [http://www.loc.gov/standards/sru/ SRU Home Page] # [http://www.loc.gov/standards/sru/specs/ SRU 1.2 Specs (Stable)] # [http://www.oasis-open.org/committees/documents.php?wg_abbrev=search-ws SRU 2.0 Specs (Public Drafts)] == Namespace == The XML namespace of the OpenSearch SRU Extension is: <nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki> This namespace and the corresponding namespace prefix "<code>sru</code>" must be included when the SRU Extension is used in an OpenSearch Description document. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:sru="<nowiki>http://a9.com/-/opensearch/extensions/sru/2.0/</nowiki>"> <nowiki><!-- Admin Details --></nowiki> <ShortName>nature.com</ShortName> <LongName>OpenSearch interface for nature.com</LongName> <Description>The nature.com OpenSearch service provides a structured resource discovery facility for content hosted on nature.com. The service implements the SRU (Search and Retrieval via URL) protocol for interacting with the nature.com database. It can be accessed both natively using the SRU protocol as well as by means of the widely adopted OpenSearch conventions. </Description> <Tags>nature.com opensearch sru</Tags> <Contact>interfaces@nature.com</Contact> <nowiki><!-- URL Template for ATOM --></nowiki> <Url type="application/atom+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/atom%2Bxml&recordPacking=unpacked&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- URL Template for SRU --></nowiki> <Url type="application/sru+xml" indexOffset="1" template="<nowiki>http://www.nature.com/opensearch/request?version=1.1&operation=searchRetrieve&query={searchTerms}&queryType={sru:queryType?}&httpAccept=application/sru%2Bxml&startRecord={startIndex?}&maximumRecords={count?}&sortKeys={sru:sortKeys?}&stylesheet={sru:stylesheet?}</nowiki>"/> <nowiki><!-- Example Queries --></nowiki> <Query role="example" sru:queryType="searchTerms" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="vampire" /> <Query role="example" sru:queryType="cql" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:sortKeys="title,pam,1" searchTerms="cql.keywords=vampire" /> <Query role="example" sru:queryType="cql" sru:stylesheet="<nowiki>http://example.org/example.xsl</nowiki>" searchTerms="cql.keywords=vampire" /> <nowiki><!-- Control Params --></nowiki> <Language>en-us</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> <SyndicationRight>open</SyndicationRight> <AdultContent>false</AdultContent> <Attribution>© 2009 Nature Publishing Group.</Attribution> </OpenSearchDescription> == Parameters == === The "queryType" parameter === <nowiki>http://example.com/?query={searchTerms}&queryTerms={sru:queryType} </nowiki> The SRU parameter "<code>queryType</code>" is a string indicating the type of query supplied in the SRU parameter "<code>query</code>" or OpenSearch parameter "<code>searchTerms</code>" - but see below for discussion of the parameter to be used. If "<code>queryType</code>" is omitted, the default is "<code>cql</code>", however this default may be overridden by the server, which may indicate a default query type via Explain. The server indicates all query types supported via Explain. The string "<code>searchTerms</code>" is a reserved value for query type. When "<code>searchTerms</code>" is used as the query type, the query may (but need not) consist of a list of terms separated by space (e.g. “<code>cat hat rat</code>”). The server processes the query however it chooses. === The "query" parameter === <nowiki>http://example.com/?query={searchTerms}&query={sru:query}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>query</code>" is a synonym for the OpenSearch parameter "<code>searchTerms</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>query</code>" is a query expressed in the query language indicated by "<code>queryType</code>" (or the default, if "<code>queryType</code>" is omitted). === The "startRecord" parameter === <nowiki>http://example.com/?query={searchTerms}&startRecord={sru:startRecord}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>startRecord</code>" is a synonym for the OpenSearch parameter "<code>startIndex</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>startRecord</code>" specifies the start of the range of the result set records. This is a positive integer, optional, and its default if omitted is 1. === The "maximumRecords" parameter === <nowiki>http://example.com/?query={searchTerms}&maximumRecords={sru:maximumRecords}</nowiki> ''(Note: This SRU parameter is provided for completeness only. The SRU parameter "<code>maximumRecords</code>" is a synonym for the OpenSearch parameter "<code>count</code>" which should be used in preference in OpenSearch URL templates.)'' The SRU parameter "<code>maximumRecords</code>" specifies that the number of records supplied is not to exceed maximumRecords. This is a non-negative integer, optional, and if omitted, the server may choose any value. (The server may return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more.) === The "recordPacking" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:recordPacking}</nowiki> The SRU parameter "<code>recordPacking</code>" specifies a packing for record data whose value is "<code>string</code>" or "<code>xml</code>" (default is "<code>xml</code>" if omitted). If the value of the parameter is "<code>string</code>", then the server should perform the conversion (escape the relevant characters) before transferring records. If the value is "<code>xml</code>", then it should embed the XML directly into the response. === The "recordSchema" parameter === <nowiki>http://example.com/?query={searchTerms}&recordSchema={sru:recordSchema}</nowiki> The SRU parameter "<code>recordSchema</code>" identifies the XML schema of the records to be supplied in the response. The value of the parameter is the short name that the server assigns to the identifier for the schema, as listed in the server’s Explain file. The default value if not supplied is determined by the server. Example: <nowiki>http://example.com/?query=dinosaur&recordSchema=mods</nowiki> === The "resultSetTTL" parameter === <nowiki>http://example.com/?query={searchTerms}&resulSetTTL={sru:resulSetTTL}</nowiki> The SRU parameter "<code>resultSetTTL</code>" specifies a period of time (in seconds) that the server should maintain the result set to be created. (Note that the server may choose not to fulfill this request, and may respond with a different value.) === The "sortKeys" parameter === <nowiki>http://example.com/?query={searchTerms}&sortKeys={sru:sortKeys}</nowiki> The SRU parameter "<code>sortKeys</code>" specifies a request for the server to sort the result set. The "<code>sortKeys</code>" parameter consists of one or more sort keys, each with sub-parameters: * <code>path</code> ** Mandatory. An XPath expression for a tagpath to be used in the sort. * <code>sortSchema</code> ** Optional. A short name for a URI identifying an XML schema to which the XPath expression applies. (The short name to URI mapping is included in the server’s Explain file.) * <code>ascending</code> ** Optional. Boolean, default "<code>true</code>". * <code>caseSensitive</code> ** Optional. Boolean, default "<code>false</code>". * <code>missingValue</code> ** Optional. Default is "<code>highValue</code>". See the SRU specification for details on representing the "<code>sortKeys</code>" parameter value. But essentially this is a space-separated list of sort keys, with individual sort keys comprised of a comma-separated sequence of sub-parameters in the order listed above. Example: <nowiki>http://example.com/?query=news&sortKeys=title,onix date,onix,,0</nowiki> This example specifies a sort primarily by "<code>title</code>" from the "<code>onix</code>" schema (with defaults of "<code>ascending</code>", "<code>insensitive</code>" and "<code>highValue</code>" for non-specified sub-parameters), and secondarily by "<code>date</code>" also from the "<code>onix</code>" schema and "<code>insensitive</code>" (with defaults of "<code>ascending</code>" and "highValue" for non-specified sub-parameters). === The "stylesheet" parameter === <nowiki>http://example.com/?query={searchTerms}&stylesheet={sru:stylesheet}</nowiki> The SRU parameter "<code>stylesheet</code>" specifies the URL for a stylesheet to be used for the display of the response to the user. Example: <nowiki>http://example.com/?query=dinosaur&stylesheet=master.xsl</nowiki> === The "rendering" parameter === <nowiki>http://example.com/?query={searchTerms}&rendering={sru:rendering}</nowiki> The SRU parameter "<code>rendering</code>" determines whether the stylesheet is to be rendered by the server or client. Its value is "<code>client</code>" or "<code>server</code>". If omitted, the default is "<code>client</code>". == Accept Parameters == === The "httpAccept" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAccept={sru:httpAccept}</nowiki> The SRU parameter "<code>httpAccept</code>" may be supplied to indicate the preferred format of the response in lieu of the "<code>Accept</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) The value is an internet media type. For example if the client wants the response to be supplied in the ATOM format, the value of the parameter is "<code>application/atom+xml</code>". The default value for the response type is "<code>application/sru+xml</code>". Example: <nowiki>http://example.com/?query=dinosaur&httpAccept=application/atom+xml</nowiki> This example specifies a query ("<code>dinosaur</code>") to an SRU server with results returned as an ATOM document. === The "httpAcceptCharset" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptCharset={sru:httpAcceptCharset}</nowiki> The SRU parameter "<code>httpAcceptCharset</code>" may be supplied in lieu of the "<code>Accept-Charset</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptEncoding" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptEncoding={sru:httpAcceptEncoding}</nowiki> The SRU parameter "<code>httpAcceptEncoding</code>" may be supplied in lieu of the "<code>Accept-Encoding</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptLanguage" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptLanguage={sru:httpAcceptLanguage}</nowiki> The SRU parameter "<code>httpAcceptLanguage</code>" may be supplied in lieu of the "<code>Accept-Language</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) === The "httpAcceptRanges" parameter === <nowiki>http://example.com/?query={searchTerms}&httpAcceptRanges={sru:httpAcceptRanges}</nowiki> The SRU parameter "<code>httpAcceptRanges</code>" may be supplied in lieu of the "<code>Accept-Ranges</code>" header field described in the HTTP Protocol specification. (For reference, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.) == Facet Parameters == === The "facetLimit" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLimit={sru:facetLimit}</nowiki> The SRU parameter "<code>facetLimit</code>" specifies the maximum number of counts that should be reported per facet field. The "<code>facetLimit</code>" parameter can be specified on a per field basis to indicate a separate limit for certain fields. Example: <nowiki>http://example.com/?query=news&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for the "<code>dc.subject</code>" index. Example: <nowiki>http://example.com/?query=news&facetLimit=10&facetLimit:dc.subject=100</nowiki> This example sets the limit to 100 for "<code>dc.subject</code>" and 10 for all other fields. The "<code>facetStart</code>" parameter <nowiki>http://example.com/?query={searchTerms}&facetStart={sru:facetStart}</nowiki> The SRU parameter "<code>facetStart</code>" specifies an offset (1-based) into the list of counts, to allow paging. The default value is 1 (meaning start with the first count). This parameter can be specified on a per field basis. Example: <nowiki>http://example.com/?query=news&facetStart=10</nowiki> This example means begin with the 10th count. Example: <nowiki>http://example.com/?query=news&facetStart:dc.subject=10</nowiki> This example means begin with the 10th count for "<code>dc.subject</code>". === The "facetSort" parameter === <nowiki>http://example.com/?query={searchTerms}&facetSort={sru:facetSort}</nowiki> The SRU parameter "<code>facetSort</code>" is a sort specification for the facet results. It is non-repeatable, and has the following components: * <code>sortBy</code> ** One of the following: *** "<code>recordCount</code>" *** "<code>alphanumeric</code>" * <code>order</code> ** Optional, one of: *** "<code>ascending</code>" (default for "<code>alphanumeric</code>") *** "<code>descending</code>" (default for "<code>recordCount</code>" or "<code>occurrence</code>") * <code>caseSensitivity</code> ** Optional, and meaningful only for "<code>alphanumeric</code>". One of: *** "<code>caseSensitive</code>" *** "<code>caseInsensitive</code>" (default) Example: <nowiki>http://example.com/?query=news&facetSort=recordCount</nowiki> Example: <nowiki>http://example.com/?query=news&facetSort=alphanumeric,descending,caseSensitive</nowiki> === The "facetRangeField" parameter === <nowiki>http://example.com/?query={searchTerms}&facetRangeField={sru:facetRangeField}</nowiki> The SRU parameter "<code>facetRangeField</code>" specifies the name of an index to be treated as a range facet. It is repeatable. Example: <nowiki>http://example.com/?query=news&facetRangeField=dateOfPublication</nowiki> === The "facetLowValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetLowValue={sru:facetLowValue}</nowiki> The SRU parameter "<code>facetLowValue</code>" specifies the lowest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetLowValue:dateOfPublication=20010101</nowiki> === The "facetHighValue" parameter === <nowiki>http://example.com/?query={searchTerms}&facetHighValue={sru:facetHighValue}</nowiki> The SRU parameter "<code>facetHighValue</code>" specifies the highest value of the specified facet range field for which facet counts should be reported. Example: <nowiki>http://example.com/?query=news&facetHighValue:dateOfPublication=20040404</nowiki> === The "facetCount" parameter === <nowiki>http://example.com/?query={searchTerms}&facetCount={sru:facetCount}</nowiki> The SRU parameter "<code>facetCount</code>" may be used to request the facet count for a specific term. The parameter may be repeated, but should not be used in conjunction with any other facet parameter. Example: <nowiki>http://example.com/?query=news&facetCount:dc.subject=history</nowiki> == Extension Parameters == === The "extension" parameter === <nowiki>http://example.com/?query={searchTerms}&x-...={sru:extension}</nowiki> The SRU extension parameter takes on the name of the extension. It must begin with "<code>x-</code>" (lowercase <code>x</code> followed by hyphen). SRU will never include an official extension with a name beginning with "<code>x-</code>", so this will never clash with a mainstream extension name. See the SRU specification for details on naming the SRU extension parameter. Example: <nowiki>http://example.com/?query=news&x-info4-onSearchFail=scan</nowiki> == Author == Tony Hammond <t.hammond@nature.com> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. Community/Proposal/Specifications/OpenSearch/Extensions/Semantic/1.0/Draft 1 1779 2375 2010-03-05T11:18:41Z Pduchesne 859 New page: == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using concepts or classification entities (or concep... == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using concepts or classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to be provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. Parameters described below are meant to build queries that return results satisfying the RDF statement <code> ?result <relation> <relatedTo> </code> ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>, and partly related to the work done in the [http://portal.opengeospatial.org/files/?artifact_id=34916 OGC Discussion Paper 08-167 : Semantic Annotations in OGC Standards]. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2376 2010-03-05T13:17:44Z Pduchesne 859 == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using concepts or classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to be provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. Parameters described below are meant to build queries that return results satisfying the RDF statement <code> ?result <relation> <relatedTo> </code> ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@gmail.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2377 2010-03-05T14:02:35Z Pduchesne 859 == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using concepts or classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to be provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@gmail.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2379 2010-03-16T11:51:17Z Pduchesne 859 /* Authors */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using concepts or classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to be provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2380 2010-03-16T11:51:57Z Pduchesne 859 /* Introduction */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to be provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2381 2010-03-16T11:52:21Z Pduchesne 859 /* Introduction */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2382 2010-03-16T11:52:50Z Pduchesne 859 /* Overview */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as concept identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2383 2010-03-16T11:53:41Z Pduchesne 859 /* Background */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as semantic entities identifiers, and a simple set of semantic operators.. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2384 2010-03-16T11:53:53Z Pduchesne 859 /* Background */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as semantic entities identifiers, and a simple set of semantic operators. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and OWL encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2385 2010-03-16T11:54:47Z Pduchesne 859 /* Example */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as semantic entities identifiers, and a simple set of semantic operators. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and RDF encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2417 2010-05-25T16:10:20Z Pduchesne 859 /* Declaring URLs to get the list of available taxonomies */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as semantic entities identifiers, and a simple set of semantic operators. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> . Taxonomy endpoints should support the <code>identifier</code> attribute, allowing the client to request a specific taxonomy. ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and RDF encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <philippe.duchesne@erdas.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] 2764 2012-02-27T16:11:44Z Pduchesne 859 /* Authors */ == Notice == {{Draft notice}} == Introduction == There is an increasing demand for search engines to be able to categorize resources using classification entities (or concepts) defined in taxonomies. That implies for the resource authors to be able to tag resources with concepts defined in authoritative taxonomies, and for the search engine to provide semantic search abilities. The OpenSearch Semantic extension offers a standard way to query a repository of resources using such semantic abilities. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two groups of [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first set of <code>Url</code> elements have a <code>rel</code> attribute with <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies</nowiki></code> as a value; it indicates to the client how to retrieve a list of taxonomies understood by the search engine. The second set of <code>Url</code> elements are the regular <code>Url</code> from the OpenSearch core specification, where the semantic operators described below can be used. == Background == The Semantic Web is building up, and several standardization efforts are looking into ways to * represent taxonomies or concept trees (RDF, OWL, SKOS, WSML, ...) * semantically annotate resources on the web using elements from those taxonomies (ISO metadata, microformats, folksonomies, ...) * devise querying schemes to exploit those semantic annotations (SPARQL) Different subsets of these technologies are used in different domains. But a common feature of all these systems is that taxonomies, concepts or other semantic entities can be unambiguously identified by URI. This allows the expression of relations (or predicates) involving concepts or entities defined in different taxonomies from different domains, using different representations languages. Therefore, a simple semantic querying scheme can be devised to be applicable to all these domains, using URIs as semantic entities identifiers, and a simple set of semantic operators. == Namespace == The XML namespace of the OpenSearch Semantic Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support semantic search can use the OpenSearch description document to publish URL templates for both retrieving the taxonomies and for performing follow-up semantic search queries. === Declaring URLs to get the list of available taxonomies === Search engines should publish one or more <code>Url</code> elements with <code><nowiki>rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"</nowiki></code> to indicate that they can be queried for a list of taxonomies that they support. Each <code>Url</code> can declare a different <code>type</code> . Taxonomy endpoints should support the <code>identifier</code> attribute, allowing the client to request a specific taxonomy. ==== Example ==== Example of declaration of taxonomy list endpoints with JSON and RDF encodings: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:semantic="<nowiki>http://a9.com/-/opensearch/extensions/semantic/1.0/</nowiki>"> '''<Url type="application/json"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.json?q={searchTerms}&identifier={identifier}</nowiki>"/>''' '''<Url type="application/rdf+xml"''' '''rel="http://a9.com/-/opensearch/extensions/semantic/1.0/taxonomies"''' '''template="<nowiki>http://example.com/taxonomies.rdf?q={searchTerms}&identifier={identifier}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ==== JSON-encoded taxonomy list ==== Taxonomy URL endpoints can be defined for any encoding type. Encodings such as OWL, SKOS, WSML are meant to represent taxonomies, and their respective specifications cover the encoding of such taxonomies. Therefore, only the JSON encoding will be described here, at it is the preferred mean for a browser to retrieve taxonomies. Taxonomies lists are returned as an array of taxonomy elements. Each taxonomy is represented as an object with the following properties : * title : a human readable name for the taxonomy * identifier : a URI uniquely identifying this taxonomy * childrenConcepts : an array of children concepts of this taxonomy Each concept is represented as an object with the following properties : * title : a human readable name for the concept * identifier : a URI uniquely identifying this * childrenConcepts : an array of children concepts of this taxonomy * (optional) classifiedObjectsCount : the number of items classified by this concept in the search engine This JSON encoding of concept trees is very simple and is not meant to be a JSON equivalent of encodings such as OWL or even SKOS. ===== Example ===== [{"title": "Wine categories", "identifier": "urn:example:taxonomy:wines" "childrenConcepts": [ {"title": "White Wine", "identifier": "urn:example:taxonomy:wines#White", "childrenConcepts": [ {"title": "Sauterne", "identifier": "urn:example:taxonomy:wines#Sauterne"}, {"title": "Chardonnay", "identifier": "urn:example:taxonomy:wines#Chardonnay"}]}, {"title": "Red Wine", "identifier": "urn:example:taxonomy:wines#Red", "childrenConcepts": [ {"title": "Bordeaux Red", "identifier": "urn:example:taxonomy:wines#BordeauxRed" }, {"title": "Syrah", "identifier": "urn:example:taxonomy:wines#Syrah" }]}, ...],}, ...] === Search parameters === After the list of taxonomies has been retrieved, the client can use some of the following parameters to query the search engine using concepts from the taxonomies retrieved. ==== The "classifiedAs" parameter ==== Replaced with comma-separated list of URIs of concepts that must classify the search results. If multiple concepts are specified, search results will have to be classified by all these concepts. If the search engine has semantic inference capabilities, this operator should match records that are classified by any concept that is equivalent to or a subconcept of the specified concepts, where 'subconcept of' and 'equivalent to' are the formal relations defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subClassOf</code> and <code>owl:equivalentClass</code>. Using this parameter is equivalent to using the <code>relation</code> and <code>related</code> parameters (below) with values being respectively <code>rdf:Type</code> and the value of <code>classifiedAs</code>. I.e. satisfying the following statement : <code> ?result rdf:Type <classifiedAs value> </code> Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&classifiedAs={semantic:classifiedAs?}&format=html</nowiki> </code> Example request, looking for english music bands, using the DBPedia taxonomy (see http://dbpedia.org/class/yago/EnglishMusicalGroups): <code> <nowiki>http://example.com/?classifiedAs=http://dbpedia.org/class/yago/EnglishMusicalGroups&format=html</nowiki> </code> ==== The "related" parameter ==== Replaced with comma-separated list of URIs of entities that the results must be related to. If multiple entities are specified, search results will have to be related to all these entities. The semantics of "related" can be specified using the <code>relation</code> parameter. If that parameter is not specified, it is up to the search engine to decide what semantic relation (or predicate) has to be satisfied. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&format=rss</nowiki> </code> Example request on a FOAF-enabled search engine where the default <code>relation</code> is <code>foaf:knows</code>. This request looks for an acquaintance of <code>urn:foaf:john.doe</code> that matches the doctor keyword. <code> <nowiki>http://example.com/?q=doctor&related=urn:foaf:john.doe&format=rss</nowiki> </code> ==== The "relation" parameter ==== Always used in conjunction with <code>related</code>. Replaced with comma-separated list of URIs identifying relations (or predicates) that must be satisfied with the <code>related</code> parameter, i.e. the results of the query must satisfy the statement : <code><nowiki> ?result <relation URI> <related URI> </nowiki></code> If multiple relations are specified, search results will have to satisfy all these relations. If the search engine has semantic inference capabilities, this operator should match records that satisfy any relation that is equivalent to or an inherited relation of the specified relation, where 'inherited' and 'equivalent to' are the formal properties defined in the [http://www.w3.org/TR/rdf-mt/#RDFSINTERP RDF] and [http://www.w3.org/TR/owl-ref/#equivalentClass-def OWL] specification, resp. <code>rdfs:subPropertyOf</code> and <code>owl:equivalentClass</code>. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>classifiedAs</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the semantic extension. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&related={semantic:related?}&relation={semantic:relation?}&format=kml</nowiki> </code> Example request, with a search engine supporting the [http://www.geonames.org/ontology/ GeoNames ontology]. This request looks for a hotel nearby Trafalgar Square (identified by its GeoName URI <code>http://sws.geonames.org/6619832</code>) : <code> <nowiki>http://example.com/?q=hotel&related=http://sws.geonames.org/6619832&relation=http://www.geonames.org/ontology%23nearby&format=kml</nowiki> </code> == Authors == This specification was edited by Philippe Duchesne <pduchesne@gmail.com>. == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft 1 1698 2157 2008-11-19T18:29:48Z Screaminggeek 241 Adding proposal for alternate Spelling extension from Medio Systems == Notice == {{Draft notice}} == Introduction == The OpenSearch Spelling Extension allows search engines to include information about a spelling suggestion in the search results. ''Example of a search result that includes spelling elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <nowiki><!-- ... --></nowiki> <spell:spelling> <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" length="0" href="<nowiki>http://example.com/opensearch?q=britney+spears&startIndex=0</nowiki>"/> </spell:spelling> <spell:related> <spell:suggestion atom:type="TEXT">beyonce</spell:suggestion> <atom:link rel="related" href="<nowiki>http://example.com/opensearch?q=beyonce</nowiki>"/> </spell:related> </feed> == Related Extensions == The [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions extension] is a [http://www.json.org/ JSON]-based method for obtaining spelling corrections and search term completions. This extension is a specification for providing spelling corrections and search suggestions alongside search results in the Atom response document. This method may be more appropriate for search results targeted to mobile devices. == Namespace == The XML namespace of the OpenSearch Mobile Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/spelling/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == === The "spelling" element === The <code>spelling</code> element is used to suggest a spelling correction for the query. Spelling correction hints may be displayed with the search results for the original query. : Requirements: This element may appear zero or one time. ''Examples of <code>spelling</code> elements:'' <spell:spelling> <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=britney+spears</nowiki>"/> </spell:spelling> <spell:spelling> <spell:suggestion atom:type="TEXT">espresso</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=espresso</nowiki>"/> </spell:spelling> ==== The "suggestion" sub-element ==== The suggestion sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the suggested spelling correction for the query. : Requirements: This element must appear one time. ''Examples of <code>suggestion</code> sub-elements:'' <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:suggestion atom:type="TEXT">espresso</spell:suggestion> ==== The "prompt" sub-element ==== The prompt sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the prompt text displayed near the spelling suggestion. : Requirements: This element must appear one time. ''Example of a <code>prompt</code> sub-element:'' <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> ==== The "link" sub-element ==== The <code>link</code> sub-element of spelling is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] whose link targets search requests for the suggested spell-corrected query. : Requirements: This element must appear one time. ''Examples of <code>link</code> sub-elements:'' <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=britney+spears&startIndex=0</nowiki>"/> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=espresso&startIndex=0</nowiki>"/> === The "related" element === The <code>related</code> element is used to suggest search terms that are related to the current query but are not spelling corrections. : Requirements: This element may appear zero or more times. ''Examples of <code>related</code> elements:'' <spell:related> <spell:suggestion atom:type="TEXT">madonna</spell:suggestion> <atom:link rel="related" href="http://example.com/opensearch?q=madonna"/> </spell:related> <spell:related> <spell:suggestion atom:type="TEXT">beyonce</spell:suggestion> <atom:link rel="related" href="http://example.com/opensearch?q=beyonce"/> </spell:related> ==== The "suggestion" sub-element ==== See the <code>suggestion</code> sub-element of <code>spelling</code> for more information. ==== The "link" sub-element ==== See the <code>link</code> sub-element of <code>spelling</code> for more information. == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2164 2008-11-20T16:21:45Z Screaminggeek 241 Updated license section per DeWitt's comments == Notice == {{Draft notice}} == Introduction == The OpenSearch Spelling Extension allows search engines to include information about a spelling suggestion in the search results. ''Example of a search result that includes spelling elements:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:advertisement="<nowiki>http://a9.com/-/opensearch/extensions/advertisement/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <nowiki><!-- ... --></nowiki> </entry> <nowiki><!-- ... --></nowiki> <spell:spelling> <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" length="0" href="<nowiki>http://example.com/opensearch?q=britney+spears&startIndex=0</nowiki>"/> </spell:spelling> <spell:related> <spell:suggestion atom:type="TEXT">beyonce</spell:suggestion> <atom:link rel="related" href="<nowiki>http://example.com/opensearch?q=beyonce</nowiki>"/> </spell:related> </feed> == Related Extensions == The [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0 OpenSearch Suggestions extension] is a [http://www.json.org/ JSON]-based method for obtaining spelling corrections and search term completions. This extension is a specification for providing spelling corrections and search suggestions alongside search results in the Atom response document. This method may be more appropriate for search results targeted to mobile devices. == Namespace == The XML namespace of the OpenSearch Mobile Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/spelling/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == === The "spelling" element === The <code>spelling</code> element is used to suggest a spelling correction for the query. Spelling correction hints may be displayed with the search results for the original query. : Requirements: This element may appear zero or one time. ''Examples of <code>spelling</code> elements:'' <spell:spelling> <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=britney+spears</nowiki>"/> </spell:spelling> <spell:spelling> <spell:suggestion atom:type="TEXT">espresso</spell:suggestion> <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=espresso</nowiki>"/> </spell:spelling> ==== The "suggestion" sub-element ==== The suggestion sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the suggested spelling correction for the query. : Requirements: This element must appear one time. ''Examples of <code>suggestion</code> sub-elements:'' <spell:suggestion atom:type="TEXT">britney spears</spell:suggestion> <spell:suggestion atom:type="TEXT">espresso</spell:suggestion> ==== The "prompt" sub-element ==== The prompt sub-element is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs atom:text construct] that specifies the prompt text displayed near the spelling suggestion. : Requirements: This element must appear one time. ''Example of a <code>prompt</code> sub-element:'' <spell:prompt atom:type="TEXT">Did you mean</spell:prompt> ==== The "link" sub-element ==== The <code>link</code> sub-element of spelling is an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link Atom Link element] whose link targets search requests for the suggested spell-corrected query. : Requirements: This element must appear one time. ''Examples of <code>link</code> sub-elements:'' <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=britney+spears&startIndex=0</nowiki>"/> <atom:link rel="spelling" href="<nowiki>http://example.com/opensearch?q=espresso&startIndex=0</nowiki>"/> === The "related" element === The <code>related</code> element is used to suggest search terms that are related to the current query but are not spelling corrections. : Requirements: This element may appear zero or more times. ''Examples of <code>related</code> elements:'' <spell:related> <spell:suggestion atom:type="TEXT">madonna</spell:suggestion> <atom:link rel="related" href="http://example.com/opensearch?q=madonna"/> </spell:related> <spell:related> <spell:suggestion atom:type="TEXT">beyonce</spell:suggestion> <atom:link rel="related" href="http://example.com/opensearch?q=beyonce"/> </spell:related> ==== The "suggestion" sub-element ==== See the <code>suggestion</code> sub-element of <code>spelling</code> for more information. ==== The "link" sub-element ==== See the <code>link</code> sub-element of <code>spelling</code> for more information. == Authors == Gail Rahn Frederick, Damon Lanphear and Michael "Luni" Libes <opensearch@medio.com> (Medio Systems) == License == This document is made available by [http://medio.com Medio Systems] subject to the terms of the [http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 License]. [[Category:Specification]] [[Category:Extension]] Community/Proposal guidelines 1460 1666 2006-09-04T15:33:34Z DeWitt 2 If you would like to contribute a proposal for a new [[Specifications/OpenSearch/Extensions|OpenSearch extension specification]], then please create a new page under the "Proposal" branch of the page hierarchy. For example, if you wanted to write an extension that would add information about the color of each search result, then you might create a page called: : <code>Community/Proposal/Specifications/OpenSearch/Extensions/Color/1.0</code> The path to your page should be contructed by prepending the prefix "Community/Proposal/" to the path that you would ultimately like the page to appear. Please do not place your page directly in the Specifications tree, as it will be moved the Community tree for public discussion and review. After a suitable period of time and discussion, an administrator can move the page into the final location. If you would like to comment on a proposal, please use the "Talk" page associated with the draft in question. 1667 2006-09-04T15:33:54Z DeWitt 2 [[Community/Proposal namespace]] moved to [[Community/Proposal guidelines]] If you would like to contribute a proposal for a new [[Specifications/OpenSearch/Extensions|OpenSearch extension specification]], then please create a new page under the "Proposal" branch of the page hierarchy. For example, if you wanted to write an extension that would add information about the color of each search result, then you might create a page called: : <code>Community/Proposal/Specifications/OpenSearch/Extensions/Color/1.0</code> The path to your page should be contructed by prepending the prefix "Community/Proposal/" to the path that you would ultimately like the page to appear. Please do not place your page directly in the Specifications tree, as it will be moved the Community tree for public discussion and review. After a suitable period of time and discussion, an administrator can move the page into the final location. If you would like to comment on a proposal, please use the "Talk" page associated with the draft in question. 1676 2006-09-04T15:43:29Z DeWitt 2 If you would like to contribute a proposal for a new [[Specifications/OpenSearch/Extensions|OpenSearch extension specification]], then please create a new page under the "Community/Proposal/" branch of the page hierarchy. For example, if you wanted to write an extension that would add information about the color of each search result, then you might create a page called: : <code>Community/Proposal/Specifications/OpenSearch/Extensions/Color/1.0</code> The path to your page should be contructed by prepending the prefix "Community/Proposal/" to the path that you would ultimately like the page to appear. Please do not place your page directly in the Specifications tree, as it will be moved the Community tree for public discussion and review. After a suitable period of time and discussion, an administrator can move the page into the final location. If you would like to comment on a proposal, please use the "Talk" page associated with the draft in question. 1677 2006-09-04T15:44:11Z DeWitt 2 If you would like to contribute a proposal for a new [[Specifications/OpenSearch/Extensions|OpenSearch extension specification]], then please create a new page under the "Community/Proposal/" branch of the page hierarchy. For example, if you wanted to write an extension that would add information about the color of each search result, then you might create a page called: : <code>Community/Proposal/Specifications/OpenSearch/Extensions/Color/1.0</code> The path to your page should be contructed by prepending the prefix "Community/Proposal/" to the path that you believe the page should ultimately appear. Please do not place your page directly in the Specifications tree, as it will be moved the Community tree for public discussion and review. After a suitable period of time and discussion, an administrator can move the page into the final location. If you would like to comment on a proposal, please use the "Talk" page associated with the draft in question. Community/Proposal namespace 1461 1668 2006-09-04T15:33:54Z DeWitt 2 [[Community/Proposal namespace]] moved to [[Community/Proposal guidelines]] #REDIRECT [[Community/Proposal guidelines]] Community/Roadmap 1463 1691 2006-09-05T14:45:46Z DeWitt 2 == Overall vision == The opensearch.org website was created by A9.com and Amazon to provide a place for the community to gather and share ideas around the format and search syndication in general. The use of a wiki-based publishing system should help facilitate the efficient incorporation of new proposals and links back to the broader community. == Plans == The OpenSearch specification is currently at Draft 3. This draft will be reviewed by the public, revised as necessary, and then marked as final. At this point, no further substantive changes (i.e., changes that would break compatibility) are anticipated. Any improvements will be focused adding clarifying details or examples. The OpenSearch 1.1 format has been stable since the first draft nearly a year ago. As the OpenSearch format was designed to be extensible, there are no concrete plans for new versions of the core OpenSearch specification in the near future. Thus search engines and search clients should feel comfortable implementing the OpenSearch 1.1 format and expect a long lifespan for the specification. 1693 2006-09-05T14:46:22Z DeWitt 2 [[Roadmap]] moved to [[Community/Roadmap]] == Overall vision == The opensearch.org website was created by A9.com and Amazon to provide a place for the community to gather and share ideas around the format and search syndication in general. The use of a wiki-based publishing system should help facilitate the efficient incorporation of new proposals and links back to the broader community. == Plans == The OpenSearch specification is currently at Draft 3. This draft will be reviewed by the public, revised as necessary, and then marked as final. At this point, no further substantive changes (i.e., changes that would break compatibility) are anticipated. Any improvements will be focused adding clarifying details or examples. The OpenSearch 1.1 format has been stable since the first draft nearly a year ago. As the OpenSearch format was designed to be extensible, there are no concrete plans for new versions of the core OpenSearch specification in the near future. Thus search engines and search clients should feel comfortable implementing the OpenSearch 1.1 format and expect a long lifespan for the specification. Community/Todo list 1465 1697 2006-09-05T15:24:26Z DeWitt 2 Things that can be done to improve the OpenSearch.org website: * Improve the MediaWiki skin. * Design a better "OpenSearch.org" logo. * Clean up the OpenSearch icons for public release. * Improve the layout of the homepage. * Reimport the old members of the [[Community/Mailing_lists|mailing lists]]. 1701 2006-09-05T15:28:49Z DeWitt 2 [[Todo list]] moved to [[Community/Todo list]] Things that can be done to improve the OpenSearch.org website: * Improve the MediaWiki skin. * Design a better "OpenSearch.org" logo. * Clean up the OpenSearch icons for public release. * Improve the layout of the homepage. * Reimport the old members of the [[Community/Mailing_lists|mailing lists]]. 1703 2006-09-05T15:31:11Z DeWitt 2 Things that can be done to improve the OpenSearch.org website: * Improve the MediaWiki skin. * Design a better "OpenSearch.org" logo. * Clean up the OpenSearch icons for public release. * Improve the layout of the homepage. * Reimport the old members of the [[Community/Mailing_lists|mailing lists]]. * Better CSS for print media. Documentation/Developer best practices guide 1430 1544 2006-08-09T14:50:39Z DeWitt 2 This page provides suggestions for making sure that your OpenSearch feeds work properly and can be discovered by search clients. == Tip: Use the proper namespace == Get your XML namespaces right. Invalid namespaces will make it impossible for search clients to parse your OpenSearch content. The [[Specifications/OpenSearch/1.1#Namespace|correct namespace]] for OpenSearch 1.1 is: <nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki> == Tip: Use autodiscovery links == This can’t be said enough. To help your OpenSearch feeds get found, use an "autodiscovery" link; it is a simple <link> element that points to a related [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]]. Include these autodiscovery 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. Read all about [[Specifications/OpenSearch/1.1#Autodiscovery|OpenSearch autodiscovery in the OpenSearch 1.1 specification]]. 1545 2006-08-09T15:08:35Z DeWitt 2 This page provides suggestions for making sure that your OpenSearch feeds work properly and can be discovered by search clients. == Use the proper namespace == Get your XML namespaces right. Invalid namespaces will make it impossible for search clients to parse your OpenSearch content. The [[Specifications/OpenSearch/1.1#Namespace|correct namespace]] for OpenSearch 1.1 is: <nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki> == Use autodiscovery links == This can’t be said enough. To help your OpenSearch feeds get found, use an "autodiscovery" link; it is a simple <link> element that points to a related [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]]. Include these autodiscovery 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. Read all about [[Specifications/OpenSearch/1.1#Autodiscovery|OpenSearch autodiscovery in the OpenSearch 1.1 specification]]. == Write informative OpenSearch description documents == Here are some tips to get you started: * Don’t mention "OpenSearch" in the ShortName, LongName, Description, or Tags elements (unless your search engine is ''about'' OpenSearch). Here is a bad description: "This searches for books by author via OpenSearch." Use "Book search by author." instead. In general, you should avoid using the word "search" except in the Description element. * The Tags element contains a list of keywords that describe the search engine. Tags such as "the" and "and" are not needed. Remember, this is not a human-readable sentence; it is meant to be tokenized and parsed by a machine. Also, tags are space-separated, so make sure you don’t separate them with commas or anything else. * You can specify more than one Image element. You should probably include at least two: one 64 by 64 pixel image, and one 16 by 16 pixel image, so that search clients can display a small icon for your search engine and a larger one for a detailed information page. Please [[Specifications/OpenSearch/1.1#The_.22Image.22_element|refer to the specification]] for more details on the Image element. * Put a valid email address in the Contact element, so that you can be notified if your OpenSearch feed is broken. * You can specify multiple Url elements, and you should do so if your search engine can return search results in HTML, RSS, Atom, or any other format. Include them all to give search clients maximum flexibility. * Specify at least one [[Specifications/OpenSearch/1.1#The_.22Query.22_element|Query element]] containing an "example" search. This example search should always return at least one search result. Search clients will use this example search to validate your OpenSearch feed. * If you search engine supports multiple languages, declare them with the [[Specifications/OpenSearch/1.1#The_.22Language.22_element|Language element]]! Or as an alternative, create a separate OpenSearch description document for each language your search engine supports, with the Description and other text in the appropriate language. If you do create multiple OpenSearch description documents, be sure to refer to all of them with [[Specifications/OpenSearch/1.1#Autodiscovery|autodiscovery links]], making use of the <code>hreflang</code> attribute as appropriate. == Tip: Use Atom to syndicate rich data == 1546 2006-08-09T15:10:03Z DeWitt 2 This page provides suggestions for making sure that your OpenSearch feeds work properly and can be discovered by search clients. == Use the proper namespace == Get your XML namespaces right. Invalid namespaces will make it impossible for search clients to parse your OpenSearch content. The [[Specifications/OpenSearch/1.1#Namespace|correct namespace]] for OpenSearch 1.1 is: <nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki> == Use autodiscovery links == This can’t be said enough. To help your OpenSearch feeds get found, use an "autodiscovery" link; it is a simple <link> element that points to a related [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]]. Include these autodiscovery 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. Read all about [[Specifications/OpenSearch/1.1#Autodiscovery|OpenSearch autodiscovery in the OpenSearch 1.1 specification]]. == Write informative OpenSearch description documents == Here are some tips to get you started: * Don’t mention "OpenSearch" in the ShortName, LongName, Description, or Tags elements (unless your search engine is ''about'' OpenSearch). Here is a bad description: "This searches for books by author via OpenSearch." Use "Book search by author." instead. In general, you should avoid using the word "search" except in the Description element. * The Tags element contains a list of keywords that describe the search engine. Tags such as "the" and "and" are not needed. Remember, this is not a human-readable sentence; it is meant to be tokenized and parsed by a machine. Also, tags are space-separated, so make sure you don’t separate them with commas or anything else. * You can specify more than one Image element. You should probably include at least two: one 64 by 64 pixel image, and one 16 by 16 pixel image, so that search clients can display a small icon for your search engine and a larger one for a detailed information page. Please [[Specifications/OpenSearch/1.1#The_.22Image.22_element|refer to the specification]] for more details on the Image element. * Put a valid email address in the Contact element, so that you can be notified if your OpenSearch feed is broken. * You can specify multiple Url elements, and you should do so if your search engine can return search results in HTML, RSS, Atom, or any other format. Include them all to give search clients maximum flexibility. * Specify at least one [[Specifications/OpenSearch/1.1#The_.22Query.22_element|Query element]] containing an "example" search. This example search should always return at least one search result. Search clients will use this example search to validate your OpenSearch feed. * If you search engine supports multiple languages, declare them with the [[Specifications/OpenSearch/1.1#The_.22Language.22_element|Language element]]! Or as an alternative, create a separate OpenSearch description document for each language your search engine supports, with the Description and other text in the appropriate language. If you do create multiple OpenSearch description documents, be sure to refer to all of them with [[Specifications/OpenSearch/1.1#Autodiscovery|autodiscovery links]], making use of the <code>hreflang</code> attribute as appropriate. 1636 2006-08-11T23:56:23Z Tesler 17 This page provides suggestions for making sure that your OpenSearch feeds work properly and can be discovered by search clients. == Use the proper namespace == Get your XML namespaces right. Invalid namespaces will make it impossible for search clients to parse your OpenSearch content. The [[Specifications/OpenSearch/1.1#Namespace|correct namespace]] for OpenSearch 1.1 is: <nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki> == Use autodiscovery links == This can’t be said enough. To help your OpenSearch feeds get found, use an "autodiscovery" link; it is a simple <link> element that points to a related [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]]. Include these autodiscovery 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. Read all about [[Specifications/OpenSearch/1.1#Autodiscovery|OpenSearch autodiscovery in the OpenSearch 1.1 specification]]. == Write informative OpenSearch description documents == Here are some tips to get you started: * Don’t mention "OpenSearch" in the ShortName, LongName, Description, or Tags elements (unless your search engine is ''about'' OpenSearch). Here is a bad description: "This searches for books by author via OpenSearch." Use "Book search by author." instead. In general, you should avoid using the word "search" except in the Description element. * The Tags element contains a list of keywords that describe the search engine. Tags such as "the" and "and" are not needed. Remember, this is not a human-readable sentence; it is meant to be tokenized and parsed by a machine. Also, tags are space-separated, so make sure you don’t separate them with commas or anything else. * You can specify more than one Image element. You should probably include at least two: one 64 by 64 pixel image, and one 16 by 16 pixel image, so that search clients can display a small icon for your search engine and a larger one for a detailed information page. Please [[Specifications/OpenSearch/1.1#The_.22Image.22_element|refer to the specification]] for more details on the Image element. * Put a valid email address in the Contact element, so that you can be notified if your OpenSearch feed is broken. * You can specify multiple Url elements, and you should do so if your search engine can return search results in HTML, RSS, Atom, or any other format. Include them all to give search clients maximum flexibility. * Specify at least one [[Specifications/OpenSearch/1.1#The_.22Query.22_element|Query element]] containing an "example" search. This example search should always return at least one search result. Search clients will use this example search to validate your OpenSearch feed. * If you search engine supports multiple languages, declare them with the [[Specifications/OpenSearch/1.1#The_.22Language.22_element|Language element]]! Or as an alternative, create a separate OpenSearch description document for each language your search engine supports, with the Description and other text in the appropriate language. If you do create multiple OpenSearch description documents, be sure to refer to all of them with [[Specifications/OpenSearch/1.1#Autodiscovery|autodiscovery links]], making use of the <code>hreflang</code> attribute as appropriate. == Check for common errors in the search results == * Try a search that doesn't have a match. Make sure you get a legitimate OpenSearch response indicating the lack of matches. Don't generate a 404 or 500 error. See [[Documentation/Developer_how_to_guide#How_to_indicate_errors|The Developer how to guide]] for more information. * Try a search with many results to make sure that paging works. Try requesting the second page of results, and see that you do indeed get the second page of results. What happens if you request a page beyond the last result? * If you also have a web based search, compare the results of the web search to the OpenSearch search. Do you get the same first result in both cases? Assuming that the page size is the same, do you get the same first result on the second page? 1944 2007-11-11T19:54:00Z Arnout 67 Use AddSearchProvider to add a search provider to IE7 or Firefox2 via a link. This page provides suggestions for making sure that your OpenSearch feeds work properly and can be discovered by search clients. == Use the proper namespace == Get your XML namespaces right. Invalid namespaces will make it impossible for search clients to parse your OpenSearch content. The [[Specifications/OpenSearch/1.1#Namespace|correct namespace]] for OpenSearch 1.1 is: <nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki> == Use autodiscovery links == This can’t be said enough. To help your OpenSearch feeds get found, use an "autodiscovery" link; it is a simple <link> element that points to a related [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]]. Include these autodiscovery 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. Read all about [[Specifications/OpenSearch/1.1#Autodiscovery|OpenSearch autodiscovery in the OpenSearch 1.1 specification]]. == Adding your search to browsers (javascript) == Aside from using autodiscovery links, both [http://msdn2.microsoft.com/en-us/library/Aa744112.aspx IE7] and [http://developer.mozilla.org/en/docs/Adding_search_engines_from_web_pages Firefox 2] can be pointed to your [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch Description document]] using a javascript call: <pre> window.external.AddSearchProvider("http://mysite.org/odd.xml"); </pre> == Write informative OpenSearch description documents == Here are some tips to get you started: * Don’t mention "OpenSearch" in the ShortName, LongName, Description, or Tags elements (unless your search engine is ''about'' OpenSearch). Here is a bad description: "This searches for books by author via OpenSearch." Use "Book search by author." instead. In general, you should avoid using the word "search" except in the Description element. * The Tags element contains a list of keywords that describe the search engine. Tags such as "the" and "and" are not needed. Remember, this is not a human-readable sentence; it is meant to be tokenized and parsed by a machine. Also, tags are space-separated, so make sure you don’t separate them with commas or anything else. * You can specify more than one Image element. You should probably include at least two: one 64 by 64 pixel image, and one 16 by 16 pixel image, so that search clients can display a small icon for your search engine and a larger one for a detailed information page. Please [[Specifications/OpenSearch/1.1#The_.22Image.22_element|refer to the specification]] for more details on the Image element. * Put a valid email address in the Contact element, so that you can be notified if your OpenSearch feed is broken. * You can specify multiple Url elements, and you should do so if your search engine can return search results in HTML, RSS, Atom, or any other format. Include them all to give search clients maximum flexibility. * Specify at least one [[Specifications/OpenSearch/1.1#The_.22Query.22_element|Query element]] containing an "example" search. This example search should always return at least one search result. Search clients will use this example search to validate your OpenSearch feed. * If you search engine supports multiple languages, declare them with the [[Specifications/OpenSearch/1.1#The_.22Language.22_element|Language element]]! Or as an alternative, create a separate OpenSearch description document for each language your search engine supports, with the Description and other text in the appropriate language. If you do create multiple OpenSearch description documents, be sure to refer to all of them with [[Specifications/OpenSearch/1.1#Autodiscovery|autodiscovery links]], making use of the <code>hreflang</code> attribute as appropriate. == Check for common errors in the search results == * Try a search that doesn't have a match. Make sure you get a legitimate OpenSearch response indicating the lack of matches. Don't generate a 404 or 500 error. See [[Documentation/Developer_how_to_guide#How_to_indicate_errors|The Developer how to guide]] for more information. * Try a search with many results to make sure that paging works. Try requesting the second page of results, and see that you do indeed get the second page of results. What happens if you request a page beyond the last result? * If you also have a web based search, compare the results of the web search to the OpenSearch search. Do you get the same first result in both cases? Assuming that the page size is the same, do you get the same first result on the second page? Documentation/Developer how to 1426 1516 2006-08-08T21:51:57Z DeWitt 2 [[Documentation/Developer how to]] moved to [[Documentation/Developer how to guide]] #REDIRECT [[Documentation/Developer how to guide]] Documentation/Developer how to guide 1423 1486 2006-08-08T16:22:03Z DeWitt 2 === How to describe a search engine's interface === 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: === How to return OpenSearch results === === How to indicate errors === === How to read OpenSearch results === === How to find OpenSearch enabled search engines === 1513 2006-08-08T21:43:32Z DeWitt 2 /* How to describe a search engine's interface */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] lists software for producing OpenSearch for popular software packages and programming languages. There are three basic steps for publishing your search results as OpenSearch: # Return your search results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSEarch response elements]]. * 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. # Two === How to return OpenSearch results === === How to indicate errors === === How to read OpenSearch results === === How to find OpenSearch enabled search engines === 1515 2006-08-08T21:51:57Z DeWitt 2 [[Documentation/Developer how to]] moved to [[Documentation/Developer how to guide]] === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] lists software for producing OpenSearch for popular software packages and programming languages. There are three basic steps for publishing your search results as OpenSearch: # Return your search results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSEarch response elements]]. * 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. # Two === How to return OpenSearch results === === How to indicate errors === === How to read OpenSearch results === === How to find OpenSearch enabled search engines === 1519 2006-08-08T22:00:52Z DeWitt 2 /* How to indicate errors */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] lists software for producing OpenSearch for popular software packages and programming languages. There are three basic steps for publishing your search results as OpenSearch: # Return your search results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSEarch response elements]]. * 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. # Two === How to return OpenSearch results === === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === 1520 2006-08-08T22:02:30Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. There are three basic steps for publishing your search results as OpenSearch: # Return your search results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSEarch response elements]]. * 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. # Two === How to return OpenSearch results === === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === 1521 2006-08-08T22:09:07Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to [http://a9.com A9.com] and other OpenSearch aggregators. === How to return OpenSearch results === === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === 1525 2006-08-08T22:13:32Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch enabled search engines|lists of OpenSearch enabled search engines]]. === How to return OpenSearch results === === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === 1526 2006-08-08T22:14:09Z DeWitt 2 /* How to return OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch enabled search engines|lists of OpenSearch enabled search engines]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === 1527 2006-08-08T22:16:47Z DeWitt 2 /* How to find OpenSearch enabled search engines */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch enabled search engines|lists of OpenSearch enabled search engines]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch enabled search engines|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1531 2006-08-08T22:19:43Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|lists of OpenSearch-enabled search engines]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch enabled search engines|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1536 2006-08-08T22:22:19Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch enabled search engines|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1537 2006-08-08T22:22:47Z DeWitt 2 /* How to find OpenSearch enabled search engines */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1538 2006-08-08T22:25:31Z DeWitt 2 /* How to read OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. If nothing meets your need, you can write something from scratch by following the [[Specification/OpenSearch/1.1|OpenSearch specification]]. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1539 2006-08-08T22:25:43Z DeWitt 2 /* How to read OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. If nothing meets your need, you can write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1540 2006-08-08T22:26:18Z DeWitt 2 /* How to read OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If that doesn't answer your question, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1542 2006-08-09T14:39:48Z DeWitt 2 /* How to return OpenSearch results from your search engine */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If those libraries don't meet your needs, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. 1632 2006-08-11T12:03:56Z DeWitt 2 /* How to find OpenSearch enabled search engines */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If those libraries don't meet your needs, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. === How to embed rich content in OpenSearch results === One solution is to use a [http://microformats.org microformats-based] approach. Please see the article on [[Documentation/Recommendations/OpenSearch_and_microformats|OpenSearch and microformats]] for more information about this technique. 2078 2008-09-17T10:07:58Z Arnout 67 /* How to read OpenSearch results */ XML Schema Definition === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If those libraries don't meet your needs, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. For generating parsing/validation/marshalling-code, an [http://lastfmapi.svn.sourceforge.net/viewvc/lastfmapi/lastfmlib/trunk/lastfmlib/src/jaxme/OpenSearch.xsd?view=markup XML Schema Definition] describing OpenSearch might come in handy. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. === How to embed rich content in OpenSearch results === One solution is to use a [http://microformats.org microformats-based] approach. Please see the article on [[Documentation/Recommendations/OpenSearch_and_microformats|OpenSearch and microformats]] for more information about this technique. 2386 2010-03-18T23:24:20Z Neti 870 /* How to read OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If those libraries don't meet your needs, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. For generating parsing/validation/marshalling-code, an [http://lastfmapi.svn.sourceforge.net/viewvc/lastfmapi/lastfmlib/trunk/lastfmlib/src/jaxme/OpenSearch.xsd?view=markup XML Schema Definition] describing OpenSearch might come in handy. hjkhjkhjk === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. === How to embed rich content in OpenSearch results === One solution is to use a [http://microformats.org microformats-based] approach. Please see the article on [[Documentation/Recommendations/OpenSearch_and_microformats|OpenSearch and microformats]] for more information about this technique. 2387 2010-04-08T18:11:25Z Intellijean 881 /* How to read OpenSearch results */ === How to return OpenSearch results from your search engine === The exact details on what needs to be done for your site depend on your particular technology. To get you started, the [[Community/OpenSearch client libraries|OpenSearch client libraries page]] contains a list of libraries that can produce OpenSearch results within popular software packages and programming languages. If those libraries don't meet your needs, there are three basic steps for publishing your search results as OpenSearch: # Modify your search engine to optionally return results in RSS or Atom format, augmented with [[Specifications/OpenSearch/1.1#OpenSearch response elements|OpenSearch response elements]]. #* Check to see if there is [[Community/OpenSearch client libraries|already software]] to do this for you. #* If you can edit the source code of your search engine, do so to support RSS or Atom based search results. #* If you can not edit the source code, then you may be able to write a wrapper around the existing search results to transform them into RSS or Atom. XSLT works well for transforming XML-based search results, and Perl and Python are good languages to scrape HTML based search results. # Create a [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] and publish it on the same host as the search engine. # Lastly, you’ll probably want to submit your OpenSearch description document to the one of the [[Community/OpenSearch search engine directories|directories of search engines that support OpenSearch]]. === How to indicate errors === There is no hard rule about how the search server should communicate error conditions to the search client. However, the technique of returning a single result containing an error message provides the end-user with an explanation as to what wrong. For example: <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:openSearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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 === You can use a publicly available search aggregator or search client, such as [[Community/OpenSearch search clients|those listed here]]. Or you can build your own search client, perhaps using one of the exisiting [[Community/OpenSearch client libraries|OpenSearch client libraries]] to get you started. And if nothing meets your exact needs, you can always write something from scratch by following the [[Specifications/OpenSearch/1.1|OpenSearch specification]]. For generating parsing/validation/marshalling-code, an [http://lastfmapi.svn.sourceforge.net/viewvc/lastfmapi/lastfmlib/trunk/lastfmlib/src/jaxme/OpenSearch.xsd?view=markup XML Schema Definition] describing OpenSearch might come in handy. === How to find OpenSearch enabled search engines === To find search engines that support OpenSearch, view [[Community/OpenSearch search engine directories|this list of sites that maintain directories of OpenSearch enabled search engines]]. === How to embed rich content in OpenSearch results === One solution is to use a [http://microformats.org microformats-based] approach. Please see the article on [[Documentation/Recommendations/OpenSearch_and_microformats|OpenSearch and microformats]] for more information about this technique. Documentation/Frequently asked questions 1421 1466 2006-08-08T14:41:21Z DeWitt 2 === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. 1467 2006-08-08T14:45:44Z DeWitt 2 /* Why OpenSearch? */ === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. 1468 2006-08-08T15:12:23Z DeWitt 2 === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more, be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1469 2006-08-08T15:15:46Z DeWitt 2 === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The OpenSearch specification defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more, be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1470 2006-08-08T15:17:00Z DeWitt 2 /* What is OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more, be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1471 2006-08-08T15:19:58Z DeWitt 2 /* Who created OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more, be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1472 2006-08-08T15:20:24Z DeWitt 2 /* How do I use OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1473 2006-08-08T15:41:21Z DeWitt 2 [[Documentation/Frequently asked questions (for users)]] moved to [[Documentation/Frequently asked questions]] === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/How_to_(for_developers)|OpenSearch "how-to" documentation for developers]]. 1477 2006-08-08T15:43:35Z DeWitt 2 /* How do I use OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1478 2006-08-08T15:44:12Z DeWitt 2 /* Why OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the formats are now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1484 2006-08-08T16:19:35Z DeWitt 2 /* Who created OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you already have a search feature on your website and you want to point search clients there, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1500 2006-08-08T17:28:17Z DeWitt 2 /* How do I use OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [Community/OpenSearch enabled search clients|OpenSearch enabled search clients]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1501 2006-08-08T17:28:33Z DeWitt 2 /* How do I use OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1514 2006-08-08T21:47:55Z DeWitt 2 === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === To learn more be sure to read the [[Documentation/Developer how to|developer "how-to" guide]]. 1518 2006-08-08T21:53:09Z DeWitt 2 /* Where can I learn more? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search spplications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1523 2006-08-08T22:11:46Z DeWitt 2 /* Who created OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1579 2006-08-09T16:31:42Z DeWitt 2 /* Who created OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1581 2006-08-09T16:41:08Z DeWitt 2 /* What is OpenSearch? */ === What is OpenSearch? === OpenSearch is a set of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1613 2006-08-09T20:08:13Z DeWitt 2 /* What is OpenSearch? */ === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and what to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1728 2006-09-05T21:27:03Z DeWitt 2 /* How do I use OpenSearch? */ === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or nagivigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1749 2006-09-08T00:32:43Z Evanm 28 /* Why use OpenSearch? */ "Nagivigated" not a word. === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or navigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interesting in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 1941 2007-11-11T17:04:02Z Arnout 67 /* Where can I learn more? */ typo === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or navigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interested in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. 2798 2012-04-13T17:26:07Z EricStob 1719 === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or navigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interested in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. === Where do I get the XSD Schemas? === 2980 2012-07-07T05:32:23Z Jgjc 1908 /* Where do I get the XSD Schemas? */ === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or navigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interested in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. === Where do I get the XSD Schemas? === <html> <head> <title>_.-حـ]ٍآٍآكمٍ الٍلٍه بٍـدٍردٍشةٍ قٍـٍلٍوٍبٍ الـــٍصوتٍـيٍه-._</title> <meta http-equiv="Content-Type" content="text/html; charset=WINDOWS-1256"> <link rel="stylesheet" href="/inc/bmc.css" type="text/css"> </head> <script Language="JavaScript"> // var hostpath, URL; hostpath = window.location.host; if (hostpath.lastIndexOf(":") >= 0) hostpath = hostpath.substring(0, hostpath.lastIndexOf(":")); hostpath = hostpath + window.location.pathname; hostpath = "http://" + hostpath.substring(0, hostpath.lastIndexOf("\/") + 1); var plugInCounter, bBMChatPlugin; var Sys = {}; var ua = navigator.userAgent.toLowerCase(); var s; (s = ua.match(/msie ([\d.]+)/)) ? Sys.ie = s[1] : (s = ua.match(/firefox\/([\d.]+)/)) ? Sys.firefox = s[1] : (s = ua.match(/chrome\/([\d.]+)/)) ? Sys.chrome = s[1] : (s = ua.match(/opera.([\d.]+)/)) ? Sys.opera = s[1] : (s = ua.match(/version\/([\d.]+).*safari/)) ? Sys.safari = s[1] : 0; if( !Sys.ie && !Sys.firefox && !Sys.chrome && !Sys.opera && !Sys.safari ){ window.location.href = "/inc/unsupported_browser_small.htm"; } if (!Sys.ie) { var plugInCounter; bBMChatPlugin = 0; for (plugInCounter = 0; plugInCounter < navigator.plugins.length; plugInCounter++) { if (navigator.plugins[plugInCounter].name.indexOf("BMChat") >= 0) { bBMChatPlugin = 1; break; } } } else bBMChatPlugin = 1; function _login() // { var trimmeduid; trimmeduid = document.form1.uid.value.replace(/(^\s*)|(\s*$)/g, ""); if (document.form1.uid.value.length == 0) { alert("من فضلك اكتب اسمك أولا حتى تستطيع الدخول ثم اضغط على كلمة الدخول بالماوس"); document.form1.uid.focus(); return; } if (document.form1.uid.value.length >= 50) { alert("Invalid Nick name for length"); document.form1.uid.focus(); return; } if (trimmeduid == "") { alert("من فضلك اكتب اسمك أولا حتى تستطيع الدخول ثم اضغط على كلمة الدخول بالماوس"); document.form1.uid.focus(); return; } if (document.form1.uid.value.indexOf("@@") != -1 || document.form1.uid.value.indexOf("&") != -1 || document.form1.uid.value.indexOf("%") != -1 || document.form1.uid.value.indexOf("+") != -1) { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } if (document.form1.uid.value.indexOf("#") != -1 || document.form1.uid.value.indexOf("*") != -1 || document.form1.uid.value.indexOf("~") != -1) { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } if (trimmeduid.substring(0, 1) == "." || trimmeduid.substring(0, 1) == "~" || trimmeduid.substring(0, 1) == ":") { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } url = "voicechat.htm?uid=" + document.form1.uid.value; if (document.form1.iBrowser.value == 2) { var bRet; bRet = false; try { if (Sys.ie) { var ILObj; ILObj = عزووووز("ILBMChat.Launcher"); bRet = عرعر ILObj.LaunchBMChat("174.37.31.175", 1990, "qloob2", 0, document.form1.uid.value, "", "C25A7C" + "ffbfbf", 1256); } else { if (bBMChatPlugin) { BMChatObj = document.getElementById("NPBMChat"); bRet = BMChatObj.Launch("174.37.31.175", 1990, "qloob2", 0, document.form1.uid.value, "", "C25A7C" + "ffbfbf", 1256); } } } catch (e) { bRet = false; } if (!bBMChatPlugin || !bRet) { if (confirm("ان برنامج نايل فويس لم يتم تحميله فى جهازك حتى الآن, هل تريد التحميل الآن؟؟")) window.open("http://174.37.31.175/inc/download.htm", ""); } } else { if (window.open(url, "", "width=788, height=544, left=0, top=0, resizable=yes, status=yes, location=no, directories=no, menubar=no, scrollbars=no") == null) alert("Prompt window blocked, please close the windows blocker and try again."); } } function getcolor() { if (Sys.ie) window.open ("iecolor.htm", "", "height=260,width=500,status=no,toolbar=no,menubar=no,location=no"); else window.open ("color.htm", "", "height=260,width=500,status=no,toolbar=no,menubar=no,location=no"); } // by zhangxinxu welcome to visit my personal website http://www.zhangxinxu.com/ var reg = /^#([0-9a-fA-f]{3}|[0-9a-fA-f]{6})$/; String.prototype.colorHex = function(){ var that = this; if(/^(rgb|RGB)/.test(that)){ var aColor = that.replace(/(?:\(|\)|rgb|RGB)*/g,"").split(","); var strHex = "#"; for(var i=0; i<aColor.length; i++){ var hex = Number(aColor[i]).toString(16); if(hex === "0"){ hex += hex; } strHex += hex; } if(strHex.length !== 7){ strHex = that; } return strHex; }else if(reg.test(that)){ var aNum = that.replace(/#/,"").split(""); if(aNum.length === 6){ return that; }else if(aNum.length === 3){ var numHex; for(var i=0; i<aNum.length; i+=1){ numHex += (aNum[i]+aNum[i]); } return numHex; } }else{ return that; } }; </Script> <body style="font-family: Verdana; font-size: 10px; color: #000000" leftmargin="0" topmargin="0" link="#666666" vlink="#666666" alink="#666666"> <form name="form1"> <table width="100%" height="100%" border="0" align="center" cellpadding="0" cellspacing="0" background="http://www9.0zz0.com/2012/05/14/16/496731378.gif" bgcolor="#DF3F5F"> <tr> <TD> <div id="tabchg" align="center"> <TABLE border=0 cellPadding=0 cellSpacing=0 height=60 width="100%" style="border-collapse: collapse" bordercolor="#111111"> <TR> <TD align=middle> <font face="Tahoma" color="#FF005F"> ادخل اسمك هنا</font></TD> </tr> <TR> <TD align="center" height="30"><font face="Tahoma"> <input maxlength="45" id="uid" name="uid" size="20" style="border-style:inset; border-width:1; BACKGROUND-COLOR: #FFFFFF; FONT-SIZE: 9pt; text-align:center; color:#FF0033" value="" tabindex="1" onkeypress="if(event.keyCode==13){_login();return false;}" enabled> </font></TD> </TR> <TR id="trbrowser" name="trbrowser" style="display:none"> <TD align="center" height="25"> <select name="iBrowser" style="border-style:outset; border-width:1px; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; FONT-SIZE: 12px;" tabindex="4"> <option value="1" style="background:#C25A7C; COLOR: #FF005F" selected>Internet Explorer</option> <option value="2" style="background:#C25A7C; COLOR: #FF005F">BMChat Application</option> </select></TD> </TR> <TR> <TD align="center" height="25"> <div align="center"> <INPUT class="form" name="btgo" type="button" value="الدخول" onClick="_login();return false" style="width:65px; border-style:outset; border-width:1px; background:#FF3F7F; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; COLOR: #FF003F; FONT-SIZE: 12px; " tabindex="2" enabled> <input class="form" name="btmember" type="button" value="دخول الأكواد" onClick="window.location.href=hostpath+'default1.asp?style=1';return(false)" style="width:65px; border-style:outset; border-width:1px; background:#FF0000; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; COLOR: #FFFFFF; FONT-SIZE: 12px; " tabindex="3"> </div></TD> </TR> </TABLE> </div></TD> </tr> </table></td> </tr> </table> </form> <script Language="JavaScript"> if (!Sys.ie) { if (bBMChatPlugin) document.write ("<embed id=\"NPBMChat\" type=\"application/x-npbmchat\" width=\"0\", height=\"0\">"); for (i = 0; i < document.form1.iBrowser.length; i++) { if (document.form1.iBrowser.options[i].value == 2) { document.form1.iBrowser.selectedIndex = i; break; } } document.getElementById("trbrowser").style.display="none"; } </script> </body> </html> 3003 2012-07-16T15:40:44Z Oal 1929 /* Where do I get the XSD Schemas? */ revert vandalism === What is OpenSearch? === OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. === Why use OpenSearch? === The web is a big place, and search engines that crawl the surface of the web are picking up only a small fraction of the great content that is out there. Moreover, some of the richest and most interesting content can not even be crawled and indexed by one search engine or navigated by one relevancy algorithm alone. Different types of content require different types of search engines. The best search engine for a particular type of content is frequently the search engine written by the people that know the content the best. OpenSearch helps search engines and search clients communicate by introducing a common set of formats to perform search requests and syndicate search results. === Who created OpenSearch? === OpenSearch was created by [http://a9.com A9.com], an [http://www.amazon.com Amazon.com] company, and the OpenSearch format is now in use by hundreds of search engines and search applications around the Internet. The OpenSearch specification is made available according to the terms of a [http://creativecommons.org/ Creative Commons] license so that everyone can participate. === How do I use OpenSearch? === If you want to view OpenSearch results, then please refer to the list of [[Community/OpenSearch enabled search clients|OpenSearch enabled search clients]]. If you run a website and want to point clients to your search engine, then you should write a simple [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] to describe the search interface. If you would like to enable third-party applications to use your search engine in unique ways, then you should also syndicate your search results by formatting them in the RSS or Atom formats, augmented with [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]]. === Where can I learn more? === If you are interested in supporting the OpenSearch format in your application, be sure to read the [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] and the [[Documentation/Developer how to guide|developer "how-to" guide]]. === Where do I get the XSD Schemas? === Documentation/Frequently asked questions (for users) 1422 1474 2006-08-08T15:41:21Z DeWitt 2 [[Documentation/Frequently asked questions (for users)]] moved to [[Documentation/Frequently asked questions]] #REDIRECT [[Documentation/Frequently asked questions]] Documentation/OpenSearch 1.0 to 1.1 upgrade guide 1450 1605 2006-08-09T19:46:08Z DeWitt 2 == Why Should I Upgrade? == OpenSearch 1.0 was a first attempt at syndicating search results in an open format. OpenSearch 1.1 is a more mature format, including many changes that came about from comments on the first version. OpenSearch 1.1 is more powerful, flexible, and extensible. Additionally, most software that produces and consumes OpenSearch will make use of the new format, so it is a good idea to stay up to date. '''But I don’t want to!''' This upgrade is actually very simple. Every effort was made to keep OpenSearch 1.1 back-compatible with OpenSearch 1.0, though there are a small number of changes that needed to be made. Bear in mind that ; there are many new features that you can now use to enhance your syndicated search results. == What changed? == This document covers only the small handful of steps that are required to upgrade. Be sure to read [[Specifications/OpenSearch/Changelog|the full changelog between OpenSearch 1.0 and OpenSearch 1.1]]. == Change the XML namespace == With OpenSearch 1.1, all parts of the OpenSearch specification were moved under a single namespace: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> You will need to change to this namespace in both your OpenSearch description documents and in your OpenSearch response feeds (formerly called OpenSearch RSS). == Update your OpenSearch description documents == === Modify the "Url" element === This is the most important change. You will need to: # Move the template URL from a child text node into the new "<code>template</code>" attribute. # Add a "<code>type</code>" attribute. ''Example of the old 1.0 Url element:'' <Url><nowiki>http://example.com/?q={searchTerms}</nowiki></Url> ''Example of the new 1.1 Url element:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>" /> === Replace the "SampleSearch" element === The old "SampleSearch" element has been replaced by the more powerful "Query" element. To convert to OpenSearch 1.1, replace your SampleSearch element with a Query element of type="example". ''Example of the old 1.0 SampleSearch element:'' <SampleSearch>cat</SampleSearch> ''Example of the new 1.1 Query element:'' <Query role="example" searchTerms="cat" /> === Remove the "Format" element === The "Format" element has been removed from OpenSearch 1.1. Remove it from your OpenSearch description document. == Update your OpenSearch response feeds == 1606 2006-08-09T19:48:25Z DeWitt 2 /* Update your OpenSearch description documents */ == Why Should I Upgrade? == OpenSearch 1.0 was a first attempt at syndicating search results in an open format. OpenSearch 1.1 is a more mature format, including many changes that came about from comments on the first version. OpenSearch 1.1 is more powerful, flexible, and extensible. Additionally, most software that produces and consumes OpenSearch will make use of the new format, so it is a good idea to stay up to date. '''But I don’t want to!''' This upgrade is actually very simple. Every effort was made to keep OpenSearch 1.1 back-compatible with OpenSearch 1.0, though there are a small number of changes that needed to be made. Bear in mind that ; there are many new features that you can now use to enhance your syndicated search results. == What changed? == This document covers only the small handful of steps that are required to upgrade. Be sure to read [[Specifications/OpenSearch/Changelog|the full changelog between OpenSearch 1.0 and OpenSearch 1.1]]. == Change the XML namespace == With OpenSearch 1.1, all parts of the OpenSearch specification were moved under a single namespace: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> You will need to change to this namespace in both your OpenSearch description documents and in your OpenSearch response feeds (formerly called OpenSearch RSS). == Update your OpenSearch description documents == To upgrade an OpenSearch description document from OpenSearch 1.0 to OpenSearch 1.1 you will need to: # [[#Modify the "Url" element|Modify the "Url" element]] # [[#Replace the "SampleSearch" element|Replace the "SampleSearch" element]] # [[#Remove the "Format" element|Remove the "Format" element]] === Modify the "Url" element === This is the most important change. You will need to: # Move the template URL from a child text node into the new "<code>template</code>" attribute. # Add a "<code>type</code>" attribute. ''Example of the old 1.0 Url element:'' <Url><nowiki>http://example.com/?q={searchTerms}</nowiki></Url> ''Example of the new 1.1 Url element:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>" /> === Replace the "SampleSearch" element === The old "SampleSearch" element has been replaced by the more powerful "Query" element. To convert to OpenSearch 1.1, replace your SampleSearch element with a Query element of type="example". ''Example of the old 1.0 SampleSearch element:'' <SampleSearch>cat</SampleSearch> ''Example of the new 1.1 Query element:'' <Query role="example" searchTerms="cat" /> === Remove the "Format" element === The "Format" element has been removed from OpenSearch 1.1. Remove it from your OpenSearch description document. == Update your OpenSearch response feeds == 1607 2006-08-09T19:48:51Z DeWitt 2 /* Update your OpenSearch description documents */ == Why Should I Upgrade? == OpenSearch 1.0 was a first attempt at syndicating search results in an open format. OpenSearch 1.1 is a more mature format, including many changes that came about from comments on the first version. OpenSearch 1.1 is more powerful, flexible, and extensible. Additionally, most software that produces and consumes OpenSearch will make use of the new format, so it is a good idea to stay up to date. '''But I don’t want to!''' This upgrade is actually very simple. Every effort was made to keep OpenSearch 1.1 back-compatible with OpenSearch 1.0, though there are a small number of changes that needed to be made. Bear in mind that ; there are many new features that you can now use to enhance your syndicated search results. == What changed? == This document covers only the small handful of steps that are required to upgrade. Be sure to read [[Specifications/OpenSearch/Changelog|the full changelog between OpenSearch 1.0 and OpenSearch 1.1]]. == Change the XML namespace == With OpenSearch 1.1, all parts of the OpenSearch specification were moved under a single namespace: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> You will need to change to this namespace in both your OpenSearch description documents and in your OpenSearch response feeds (formerly called OpenSearch RSS). == Update your OpenSearch description documents == To upgrade an OpenSearch description document from OpenSearch 1.0 to OpenSearch 1.1 you will need to: # [[#Change the XML namespace|Change the XML namespace]] # [[#Modify the "Url" element|Modify the "Url" element]] # [[#Replace the "SampleSearch" element|Replace the "SampleSearch" element]] # [[#Remove the "Format" element|Remove the "Format" element]] === Modify the "Url" element === This is the most important change. You will need to: # Move the template URL from a child text node into the new "<code>template</code>" attribute. # Add a "<code>type</code>" attribute. ''Example of the old 1.0 Url element:'' <Url><nowiki>http://example.com/?q={searchTerms}</nowiki></Url> ''Example of the new 1.1 Url element:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>" /> === Replace the "SampleSearch" element === The old "SampleSearch" element has been replaced by the more powerful "Query" element. To convert to OpenSearch 1.1, replace your SampleSearch element with a Query element of type="example". ''Example of the old 1.0 SampleSearch element:'' <SampleSearch>cat</SampleSearch> ''Example of the new 1.1 Query element:'' <Query role="example" searchTerms="cat" /> === Remove the "Format" element === The "Format" element has been removed from OpenSearch 1.1. Remove it from your OpenSearch description document. == Update your OpenSearch response feeds == 1608 2006-08-09T19:58:29Z DeWitt 2 == Why Should I Upgrade? == OpenSearch 1.0 was a first attempt at syndicating search results in an open format. OpenSearch 1.1 is a more mature format, including many changes that came about from comments on the first version. OpenSearch 1.1 is more powerful, flexible, and extensible. Additionally, most software that produces and consumes OpenSearch will make use of the new format, so it is a good idea to stay up to date. '''But I don’t want to!''' This upgrade is actually very simple. Every effort was made to keep OpenSearch 1.1 back-compatible with OpenSearch 1.0, though there are a small number of changes that needed to be made. Bear in mind that ; there are many new features that you can now use to enhance your syndicated search results. == What changed? == This document covers only the small handful of steps that are required to upgrade. Be sure to read [[Specifications/OpenSearch/Changelog|the full changelog between OpenSearch 1.0 and OpenSearch 1.1]]. == Upgrade steps == To upgrade, you will need to: # [[#Update your OpenSearch description documents|Update your OpenSearch description documents]] # [[#Update your OpenSearch response feeds|Update your OpenSearch response feeds]] === Change the XML namespace === With OpenSearch 1.1, all parts of the OpenSearch specification were moved under a single namespace: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> You will need to change to this namespace in both your OpenSearch description documents and in your OpenSearch response feeds (formerly called OpenSearch RSS). === Update your OpenSearch description documents === To upgrade an OpenSearch description document from OpenSearch 1.0 to OpenSearch 1.1 you will need to: # [[#Change the XML namespace|Change the XML namespace]] # [[#Modify the "Url" element|Modify the "Url" element]] # [[#Replace the "SampleSearch" element|Replace the "SampleSearch" element]] # [[#Remove the "Format" element|Remove the "Format" element]] ==== Modify the "Url" element ==== This is the most important change. You will need to: # Move the template URL from a child text node into the new "<code>template</code>" attribute. # Add a "<code>type</code>" attribute. ''Example of the old 1.0 Url element:'' <Url><nowiki>http://example.com/?q={searchTerms}</nowiki></Url> ''Example of the new 1.1 Url element:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>" /> ==== Replace the "SampleSearch" element ==== The old "SampleSearch" element has been replaced by the more powerful "Query" element. To convert to OpenSearch 1.1, replace your SampleSearch element with a Query element of type="example". ''Example of the old 1.0 SampleSearch element:'' <SampleSearch>cat</SampleSearch> ''Example of the new 1.1 Query element:'' <Query role="example" searchTerms="cat" /> ==== Remove the "Format" element ==== The "Format" element has been removed from OpenSearch 1.1. Remove it from your OpenSearch description document. === Update your OpenSearch response feeds === To upgrade an OpenSearch response (formerly called OpenSearch RSS) from OpenSearch 1.0 to OpenSearch 1.1 you will simply need to: # [[#Change the XML namespace|Change the XML namespace]] Of course, you will likely want to explore other types of result formats (such as Atom 1.0) and the [[Specifications/OpenSearch/1.1#OpenSearch response elements|wealth of powerful functionality]] available in OpenSearch 1.1. 1609 2006-08-09T19:58:51Z DeWitt 2 /* Update your OpenSearch response feeds */ == Why Should I Upgrade? == OpenSearch 1.0 was a first attempt at syndicating search results in an open format. OpenSearch 1.1 is a more mature format, including many changes that came about from comments on the first version. OpenSearch 1.1 is more powerful, flexible, and extensible. Additionally, most software that produces and consumes OpenSearch will make use of the new format, so it is a good idea to stay up to date. '''But I don’t want to!''' This upgrade is actually very simple. Every effort was made to keep OpenSearch 1.1 back-compatible with OpenSearch 1.0, though there are a small number of changes that needed to be made. Bear in mind that ; there are many new features that you can now use to enhance your syndicated search results. == What changed? == This document covers only the small handful of steps that are required to upgrade. Be sure to read [[Specifications/OpenSearch/Changelog|the full changelog between OpenSearch 1.0 and OpenSearch 1.1]]. == Upgrade steps == To upgrade, you will need to: # [[#Update your OpenSearch description documents|Update your OpenSearch description documents]] # [[#Update your OpenSearch response feeds|Update your OpenSearch response feeds]] === Change the XML namespace === With OpenSearch 1.1, all parts of the OpenSearch specification were moved under a single namespace: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> You will need to change to this namespace in both your OpenSearch description documents and in your OpenSearch response feeds (formerly called OpenSearch RSS). === Update your OpenSearch description documents === To upgrade an OpenSearch description document from OpenSearch 1.0 to OpenSearch 1.1 you will need to: # [[#Change the XML namespace|Change the XML namespace]] # [[#Modify the "Url" element|Modify the "Url" element]] # [[#Replace the "SampleSearch" element|Replace the "SampleSearch" element]] # [[#Remove the "Format" element|Remove the "Format" element]] ==== Modify the "Url" element ==== This is the most important change. You will need to: # Move the template URL from a child text node into the new "<code>template</code>" attribute. # Add a "<code>type</code>" attribute. ''Example of the old 1.0 Url element:'' <Url><nowiki>http://example.com/?q={searchTerms}</nowiki></Url> ''Example of the new 1.1 Url element:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>" /> ==== Replace the "SampleSearch" element ==== The old "SampleSearch" element has been replaced by the more powerful "Query" element. To convert to OpenSearch 1.1, replace your SampleSearch element with a Query element of type="example". ''Example of the old 1.0 SampleSearch element:'' <SampleSearch>cat</SampleSearch> ''Example of the new 1.1 Query element:'' <Query role="example" searchTerms="cat" /> ==== Remove the "Format" element ==== The "Format" element has been removed from OpenSearch 1.1. Remove it from your OpenSearch description document. === Update your OpenSearch response feeds === To upgrade an OpenSearch response feed (formerly called OpenSearch RSS) from OpenSearch 1.0 to OpenSearch 1.1 you will simply need to: # [[#Change the XML namespace|Change the XML namespace]] Of course, you will likely want to explore other types of result formats (such as Atom 1.0) and the [[Specifications/OpenSearch/1.1#OpenSearch response elements|wealth of powerful functionality]] available in OpenSearch 1.1. Documentation/Recommendations/OpenSearch and microformats 1431 1548 2006-08-09T15:18:14Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == "Microformats are a set of simple, open data formats built upon existing and widely adopted standards for the purpose of adding machine-readable semantic meaning to human-readable content." (From "[http://microformats.org/about/ About Microformats]") In the same way, OpenSearch is a set of simple, open data formats built upon existing and widely adopted standards for the purpose of sharing search results. The goals and philosophies of the two initiatives are highly compatible; OpenSearch and microformats can work together in bringing rich data to end users simply and intuitively. The microformat approach of adding semantic markup to existing and human-readable content works particularly well within the context of search. OpenSearch search engines can return search results in a human-readable XHTML format; thus it is easy to apply a well-defined layer of semantic markup to indicate the underlying meaning of that content. == Interoperability == Microformats offer a convenient way of adding machine-readable semantic information to human-readable search results. The use of microformats in an OpenSearch context does not preclude the use of alternate techniques. == Namespaces == All elements, attributes, and parameters in an OpenSearch context must be associated with an XML namespace. === Microformats with XMDP profiles === If a microformat declares a formal XMDP profile then the XMDP profile URI should be used as the XML namespace name. === Microformats without XMDP profiles === If a microformat does not declare a formal XMDP profile then the most reasonable homepage URI for the microformat markup should be used as the XML namespace name. === Example namespaces === ''Example XML namespaces for common microformats:'' xmlns:hcalendar="<nowiki>http://microformats.org/wiki/hcalendar</nowiki>" xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>" xmlns:hreview="<nowiki>http://microformats.org/wiki/hreview</nowiki>" xmlns:xfn="<nowiki>http://www.gmpg.org/xfn/11</nowiki>" == Responses == Microformats can be used in OpenSearch response formats that contain explicitly typed and well-formed markup, such as XHTML text constructs in Atom 1.0. Care must be taken to ensure that the client can reasomably parse and interperent any microformat information, thus microformats can not be reliably used with opaque or unstructured search result content, such as encoded HTML. === Atom 1.0 Responses === ==== Elements that can contain microformat markup ==== Microformat markup can be used in the Atom 1.0 elements classified as [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs text constructs], such as <code>atom:title</code>, <code>atom:subtitle</code>, <code>atom:summary</code>, and <code>atom:content</code>. ==== XHTML content ==== Text construct elements must be of <code>type="xhtml"</code> to be parsed for microformat content. ==== Other content ==== Text construct elements of <code>type="text"</code> and <code>type="html"</code> are considered opaque and can not be parsed for microformat content. ==== Resolving ambiguities ==== If an entry contains both an <code>atom:summary</code> element and an <code>atom:content</code> element then only content of the <code>atom:summary</code> element should be displayed to the end-user. The <code>atom:content</code> element may still be parsed for microformat markup. ==== Example Atom 1.0 response ==== ''Example Atom 1.0-based OpenSearch response with microformat content:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Phonebook Search</title> <nowiki><!-- ... --></nowiki> <entry> <title>Jane Smith</title> <link href="<nowiki>http://example.com/people/jsmith</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <summary type="xhtml"> '''<nowiki><div xmlns="http://www.w3.org/1999/xhtml" class="vcard"> <div class="n"> <span class="honorific-prefix">Ms.</span> <span class="given-name">Jane</span> <span class="family-name">Smith</span> </div> <div class="tel"> <span class="type">Work</span>: <span class="value">(212) 555-0101</span> </div> </div></nowiki>''' </summary> </entry> </feed> === RSS 2.0 Responses === Search engines that wish to include semantic markup in OpenSearch results are encouraged to use the Atom 1.0 syndication format instead of RSS 2.0. The <code>description</code> element in RSS 2.0 does not convey enough formal context about the type or encoding of the enclosed content to reliably be used to deliver machine-readable semantic data. == URL Templates == Microformat class names can be used in OpenSearch URL templates to provide conventional query parameter names. === Parameter namespaces === All template query parameter in the template must be associated with an XML namespace name via an XML namespace prefix. === Optional Parameters === The search server can use the "<code>?</code>" flag when requesting a microformat-based parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. === Example URL templates === ''Example of the hCalendar microformat used in an OpenSearch URL template:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcalendar="<nowiki>http://microformats.org/wiki/hcalendar</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;start={</nowiki>'''hcalendar:dtstart?'''}&amp;end={'''hcalendar:dtend?'''}"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ''Example of the hCard microformat used in an OpenSearch URL template:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;address={</nowiki>'''hcard:adr?'''}"/> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;zip={</nowiki>'''hcard:postal-code?'''}"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Query Elements == Microformat classes can be used as attribute names in OpenSearch Query elements. Each fully qualified attribute name corresponds to a parameter in an OpenSearch URL template. === Query attribute namespaces === Each attribute in the Query element must be associated with an XML namespace name. === Example Query elements === ''Example of microformats in OpenSearch Query elements:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?city={'''hcard:locality?'''}&amp;state={'''hcard:region?'''}&amp;country={'''hcard:country-name?'''}&amp;zip={'''hcard:postal-code?'''}"/> <Query role="example" searchTerms="pizza" '''hcard:postal-code="94117"''' /> <Query role="example" searchTerms="car dealership" '''hcard:locality="San Francisco"''' '''hcard:region="California"''' /> <Query role="example" searchTerms="hydroelectric dam" '''hcard:country-name="United States"''' /> <!-- ... --> </OpenSearchDescription> == Author == DeWitt Clinton <dewitt@opensearch.org> == Further Reading == * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] * [http://www.atomenabled.org/developers/syndication/atom-format-spec.php Atom 1.0 Specification] * [http://www.microformats.org Microformats website] 1974 2008-01-13T22:34:14Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == "Microformats are a set of simple, open data formats built upon existing and widely adopted standards for the purpose of adding machine-readable semantic meaning to human-readable content." (From "[http://microformats.org/about/ About Microformats]") In the same way, OpenSearch is a set of simple, open data formats built upon existing and widely adopted standards for the purpose of sharing search results. The goals and philosophies of the two initiatives are highly compatible; OpenSearch and microformats can work together in bringing rich data to end users simply and intuitively. The microformat approach of adding semantic markup to existing and human-readable content works particularly well within the context of search. OpenSearch search engines can return search results in a human-readable XHTML format; thus it is easy to apply a well-defined layer of semantic markup to indicate the underlying meaning of that content. == Interoperability == Microformats offer a convenient way of adding machine-readable semantic information to human-readable search results. The use of microformats in an OpenSearch context does not preclude the use of alternate techniques. == Namespaces == All elements, attributes, and parameters in an OpenSearch context must be associated with an XML namespace. === Microformats with XMDP profiles === If a microformat declares a formal XMDP profile then the XMDP profile URI should be used as the XML namespace name. === Microformats without XMDP profiles === If a microformat does not declare a formal XMDP profile then the most reasonable homepage URI for the microformat markup should be used as the XML namespace name. === Example namespaces === ''Example XML namespaces for common microformats:'' xmlns:hcalendar="<nowiki>http://microformats.org/wiki/hcalendar</nowiki>" xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>" xmlns:hreview="<nowiki>http://microformats.org/wiki/hreview</nowiki>" xmlns:xfn="<nowiki>http://www.gmpg.org/xfn/11</nowiki>" == Responses == Microformats can be used in OpenSearch response formats that contain explicitly typed and well-formed markup, such as XHTML text constructs in Atom 1.0. Care must be taken to ensure that the client can reasonably parse and interpret any microformat information, thus microformats can not be reliably used with opaque or unstructured search result content, such as encoded HTML. === Atom 1.0 Responses === ==== Elements that can contain microformat markup ==== Microformat markup can be used in the Atom 1.0 elements classified as [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#text.constructs text constructs], such as <code>atom:title</code>, <code>atom:subtitle</code>, <code>atom:summary</code>, and <code>atom:content</code>. ==== XHTML content ==== Text construct elements must be of <code>type="xhtml"</code> to be parsed for microformat content. ==== Other content ==== Text construct elements of <code>type="text"</code> and <code>type="html"</code> are considered opaque and can not be parsed for microformat content. ==== Resolving ambiguities ==== If an entry contains both an <code>atom:summary</code> element and an <code>atom:content</code> element then only content of the <code>atom:summary</code> element should be displayed to the end-user. The <code>atom:content</code> element may still be parsed for microformat markup. ==== Example Atom 1.0 response ==== ''Example Atom 1.0-based OpenSearch response with microformat content:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Phonebook Search</title> <nowiki><!-- ... --></nowiki> <entry> <title>Jane Smith</title> <link href="<nowiki>http://example.com/people/jsmith</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <summary type="xhtml"> '''<nowiki><div xmlns="http://www.w3.org/1999/xhtml" class="vcard"> <div class="n"> <span class="honorific-prefix">Ms.</span> <span class="given-name">Jane</span> <span class="family-name">Smith</span> </div> <div class="tel"> <span class="type">Work</span>: <span class="value">(212) 555-0101</span> </div> </div></nowiki>''' </summary> </entry> </feed> === RSS 2.0 Responses === Search engines that wish to include semantic markup in OpenSearch results are encouraged to use the Atom 1.0 syndication format instead of RSS 2.0. The <code>description</code> element in RSS 2.0 does not convey enough formal context about the type or encoding of the enclosed content to reliably be used to deliver machine-readable semantic data. == URL Templates == Microformat class names can be used in OpenSearch URL templates to provide conventional query parameter names. === Parameter namespaces === All template query parameter in the template must be associated with an XML namespace name via an XML namespace prefix. === Optional Parameters === The search server can use the "<code>?</code>" flag when requesting a microformat-based parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. === Example URL templates === ''Example of the hCalendar microformat used in an OpenSearch URL template:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcalendar="<nowiki>http://microformats.org/wiki/hcalendar</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;start={</nowiki>'''hcalendar:dtstart?'''}&amp;end={'''hcalendar:dtend?'''}"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> ''Example of the hCard microformat used in an OpenSearch URL template:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;address={</nowiki>'''hcard:adr?'''}"/> <Url type="application/atom+xml" template="<nowiki>http://example.com?q={searchTerms}&amp;zip={</nowiki>'''hcard:postal-code?'''}"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Query Elements == Microformat classes can be used as attribute names in OpenSearch Query elements. Each fully qualified attribute name corresponds to a parameter in an OpenSearch URL template. === Query attribute namespaces === Each attribute in the Query element must be associated with an XML namespace name. === Example Query elements === ''Example of microformats in OpenSearch Query elements:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:hcard="<nowiki>http://www.w3.org/2006/03/hcard</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?city={'''hcard:locality?'''}&amp;state={'''hcard:region?'''}&amp;country={'''hcard:country-name?'''}&amp;zip={'''hcard:postal-code?'''}"/> <Query role="example" searchTerms="pizza" '''hcard:postal-code="94117"''' /> <Query role="example" searchTerms="car dealership" '''hcard:locality="San Francisco"''' '''hcard:region="California"''' /> <Query role="example" searchTerms="hydroelectric dam" '''hcard:country-name="United States"''' /> <!-- ... --> </OpenSearchDescription> == Author == DeWitt Clinton <dewitt@opensearch.org> == Further Reading == * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 specification]] * [http://www.atomenabled.org/developers/syndication/atom-format-spec.php Atom 1.0 Specification] * [http://www.microformats.org Microformats website] Documentation/Stylesheet 1449 1597 2006-08-09T18:43:06Z DeWitt 2 == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specification/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Settings === === Customize anything === === Within another page === === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1598 2006-08-09T18:43:25Z DeWitt 2 /* Features */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Settings === === Customize anything === === Within another page === === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1599 2006-08-09T18:47:37Z DeWitt 2 /* Advanced usage */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Settings === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Customize anything === === Within another page === === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1600 2006-08-09T18:48:30Z DeWitt 2 /* Customize anything */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Settings === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Customize anything === Any of the files can be customized all you want. Go crazy! === Within another page === === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1601 2006-08-09T18:49:05Z DeWitt 2 /* Settings */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Translations and text changes === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Settings === The text used for translations is also used for settings, such as whether or not to display author information if it is available. The options are described in the source code, so see the above section for details. === Customize anything === Any of the files can be customized all you want. Go crazy! === Within another page === === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1602 2006-08-09T18:49:52Z DeWitt 2 /* Within another page */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Translations and text changes === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Settings === The text used for translations is also used for settings, such as whether or not to display author information if it is available. The options are described in the source code, so see the above section for details. === Customize anything === Any of the files can be customized all you want. Go crazy! === Within another page === The stylesheet is currently designed to create a whole web page. If you want to display an OpenSearch feed within another page, then you will have to use the XSLT on your web server and modify it to remove some of the redundant surrounding HTML markup. === Technical details === == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1603 2006-08-09T18:51:33Z DeWitt 2 /* Technical details */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * os.xsl - the XSLT (primary file) * os.css - the CSS stylesheet * os.js - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Translations and text changes === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Settings === The text used for translations is also used for settings, such as whether or not to display author information if it is available. The options are described in the source code, so see the above section for details. === Customize anything === Any of the files can be customized all you want. Go crazy! === Within another page === The stylesheet is currently designed to create a whole web page. If you want to display an OpenSearch feed within another page, then you will have to use the XSLT on your web server and modify it to remove some of the redundant surrounding HTML markup. === Technical details === The stylesheet is an [http://www.w3.org/TR/xslt XSLT]. Modern web browsers such as Firefox, Internet Explorer, Safari (1.3 and up), and Opera have XSLT parsers built-in. If you would prefer to do the transformation on your web server (rather than client-side), you’ll need to make use of one of the publicly available XSLT parsers. The XSLT parser used by the Mozilla browser (and derivatives, such as Firefox) does not support a certain XSLT command that is required for the stylesheet to work properly. The Javascript file (os.js) available here corrects for that problem. If you know you won’t need to deal with that parser, then you do not need the Javascript file, and you should modify the "<code>use-doe-hack</code>" variable near the top of the stylesheet. == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> 1604 2006-08-09T19:29:21Z DeWitt 2 /* The files */ == So, you want to display search results on your website? == Provided here is a stylesheet (XSL file) that will convert RSS and Atom based OpenSearch search result feeds into HTML. You can use it on your website, or anywhere else, for free, as they are made available under a [[#License|Creative Commons license]]. It is a good idea to use this stylesheet on your own OpenSearch feeds, so that users can see actual search results instead of raw XML. == The files == Here are the three files used: the stylesheet, and two associated files. * [http://69.55.232.189/downloads/opensearch_to_html.xsl opensearch_to_html.xsl] - the XSLT (primary file) * [http://69.55.232.189/downloads/opensearch_to_html.css opensearch_to_html.css]- the CSS stylesheet * [http://69.55.232.189/downloads/opensearch_to_html.js opensearch_to_html.js] - the Javascript file (see [[#Technical details|technical details]]) == How to use the stylesheet == === Step 1: Find an OpenSearch feed that you want to display === See the [[Community/OpenSearch search engine directories|list of OpenSearch search engine directories]] for pointers to plenty of OpenSearch feeds. === Step 2: Get the files === Download [[#The files|the three files]] listed above. The os.xsl file is required. The os.css file makes it look pretty, so you will probably want that too. The os.js file is used to handle web browsers that don’t support all of the stylesheet functionality needed (details). Save the files to some location where they can be accessed over the Internet via an HTTP. Or save them on a filesystem if you indend to use them locally. === Step 2: Apply the stylesheet === The style sheet can be applied either by a standalone parser, or performed in-line by a search client, such as a web browser. ==== In-line transformation ==== To use the XSLT parser build most modern web browsers, or make use of another parser, simply add a link to the style sheet in the OpenSearch response feed, right below the XML declaration. For example: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet href="os.xsl" type="text/xsl" ?> <rss version="2.0" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... --></nowiki> </rss> You may need to adjust the links to the next and previous pages of search results so that they also have the stylesheet applied to them. ==== Stand-alone transformation ==== == Features == The stylesheet will transform most valid OpenSearchs feed into HTML. Assuming that the feed contains valid XHTML (or no HTML at all), the transformation should be valid XHTML 1.0. Please note that potentially malicious code (such as Javascript) is not dealt with. The stylesheet is capable of transforming both OpenSearch 1.0 and OpenSearch 1.1 response feeds, in any of the following syndication formats: RSS 0.9, 0.91, 0.92, 0.93, 1.0, and 2.0, and Atom 1.0. The stylesheet does not yet make use of the [[Specifications/OpenSearch/1.1#OpenSearch Query element|OpenSearch Query element]]. The stylesheet is liberal, which means that it will try to make errors invisible to the user (it should "just work"), even if there are problems with the OpenSearch elements, or even if there is no feed at all. The stylesheet makes use of a variety of information, including supporting a number of RSS/Atom elements and popular extensions, such as author and category information. This, along with all text on the page, is configurable; see [[#Advanced usage|advanced usage]]. == Advanced usage == === Translations and text changes === It is quite simple to change any of the text used by the stylesheet to mark up the search results. There is a section at the top of the os.xsl file where all the bits of text used are stored, along with descriptions of what each is used for. You can edit the os.xsl file in any text editor. The section to edit should be easy to find; it is near the top, just below the <code><xsl:output/></code> element. Each string is contained within a <code><xls:variable/></code> element with a name describing the text. For example, the following element defines the text that is displayed when there are no search results: <xls:variable name="t-noresults">Sorry, no results were found.</xsl:variable> Note, the language of the actual OpenSearch results are not affected by the stylesheet; just the text that the stylesheet adds on top of that. === Settings === The text used for translations is also used for settings, such as whether or not to display author information if it is available. The options are described in the source code, so see the above section for details. === Customize anything === Any of the files can be customized all you want. Go crazy! === Within another page === The stylesheet is currently designed to create a whole web page. If you want to display an OpenSearch feed within another page, then you will have to use the XSLT on your web server and modify it to remove some of the redundant surrounding HTML markup. === Technical details === The stylesheet is an [http://www.w3.org/TR/xslt XSLT]. Modern web browsers such as Firefox, Internet Explorer, Safari (1.3 and up), and Opera have XSLT parsers built-in. If you would prefer to do the transformation on your web server (rather than client-side), you’ll need to make use of one of the publicly available XSLT parsers. The XSLT parser used by the Mozilla browser (and derivatives, such as Firefox) does not support a certain XSLT command that is required for the stylesheet to work properly. The Javascript file (os.js) available here corrects for that problem. If you know you won’t need to deal with that parser, then you do not need the Javascript file, and you should modify the "<code>use-doe-hack</code>" variable near the top of the stylesheet. == Author == Michael Fagan <mifa@a9.com> == Contributors == Joel Tesler <tesler@a9.com>, DeWitt Clinton <dewitt@opensearch.org> Home 1410 1437 2006-07-25T16:59:08Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ** [[Specifications/Extensions|OpenSearch extensions]] ** [[Specifications/License|License]] ** [[Specification/Changelog|Specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1443 2006-07-25T18:11:35Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ** [[Specifications/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specification/Changelog|Specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1450 2006-07-25T20:15:11Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ** [[Specifications/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/Changelog|Specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1453 2006-07-25T20:16:02Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ** [[Specifications/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1457 2006-07-25T20:19:44Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1465 2006-08-08T14:30:57Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions (for users)|Frequently asked questions from users]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1475 2006-08-08T15:41:39Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Frequently asked questions (for developers)|Frequently asked questions from developers]] ** [[Documentation/How to (for developers)|"How to" for developers]] ** [[Documentation/Best practices (for developers)|Best practices with OpenSearch]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1476 2006-08-08T15:43:04Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] 1479 2006-08-08T16:12:34Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * [[Specifications]] ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] 1480 2006-08-08T16:13:05Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] 1481 2006-08-08T16:15:09Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch™ is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available using the OpenSearch formats. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1482 2006-08-08T16:15:57Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1|OpenSearch specification]] defines a way for a search engine to describe its public interface and a way for search results to be syndicated across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1483 2006-08-08T16:18:55Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1511 2006-08-08T17:56:18Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1512 2006-08-08T17:56:38Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to|Developer "how to" guide]] ** [[Documentation/Developer best practices|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1517 2006-08-08T21:52:12Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1522 2006-08-08T22:10:24Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search engines|Lists of search engines that support OpenSearch]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1524 2006-08-08T22:12:16Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch enabled search engines|Lists of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1528 2006-08-08T22:17:37Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of OpenSearch-enabled search engines]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1532 2006-08-08T22:20:31Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch enabled search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1535 2006-08-08T22:20:54Z DeWitt 2 /* For everyone */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] 1547 2006-08-09T15:12:25Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch client libraries|Client libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] 1553 2006-08-09T15:35:51Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] 1580 2006-08-09T16:40:33Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] 1582 2006-08-09T16:41:27Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] 1593 2006-08-09T17:17:08Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] ** [[Community/Mailing lists]] 1594 2006-08-09T17:17:19Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a set of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] ** [[Community/Mailing lists|Mailing lists]] 1612 2006-08-09T20:07:57Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] ** [[Community/Mailing lists|Mailing lists]] 1614 2006-08-09T20:08:56Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Contact|Contact]] ** [[Community/Mailing lists|Mailing lists]] 1615 2006-08-09T20:10:09Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1619 2006-08-09T23:10:59Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1620 2006-08-09T23:11:30Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use [[Specifications/OpenSearch/1.1|OpenSearch formats]] to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1633 2006-08-11T12:04:41Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1645 2006-08-14T16:45:56Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|OpenSearch.org editorial guidelines]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1646 2006-08-14T17:47:34Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1647 2006-08-15T15:26:58Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1655 2006-08-21T16:19:03Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. You can use OpenSearch formats to help people discover and use your search engine and to syndicate search results across the web. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1656 2006-08-23T07:09:14Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. And the [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1657 2006-08-23T07:12:57Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/OpenSearch icons|OpenSearch icons]] ** [[Community/Mailing lists|Mailing lists]] 1663 2006-09-02T12:14:54Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Mailing lists|Mailing lists]] 1664 2006-09-02T15:13:32Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch libraries|Libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Mailing lists|Mailing lists]] 1674 2006-09-04T15:40:10Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Mailing lists|Mailing lists]] 1679 2006-09-05T13:03:50Z DeWitt 2 /* Introduction */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Mailing lists|Mailing lists]] 1692 2006-09-05T14:46:11Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Roadmap|OpenSearch roadmap]] ** [[Community/Mailing lists|Mailing lists]] 1696 2006-09-05T15:16:14Z DeWitt 2 /* For developers */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == Areas of interest == === For everyone === * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] === For developers === * Specifications ** [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] *** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] *** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] *** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] *** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] ** [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] *** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] *** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] *** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] *** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] ** [[Specifications/Archive|Archived specifications]] ** [[Specifications/License|License]] ** [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] * Documentation ** [[Documentation/Developer how to guide|Developer "how to" guide]] ** [[Documentation/Developer best practices guide|Developer "best practices" guide]] ** [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] ** [[Documentation/Stylesheet|OpenSearch response stylesheet]] ** [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] * Community ** [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] ** [[Community/Guidelines|Editorial guidelines]] ** [[Community/Roadmap|OpenSearch roadmap]] ** [[Community/Mailing lists|Mailing lists]] 1699 2006-09-05T15:27:34Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] 1700 2006-09-05T15:28:36Z DeWitt 2 /* Community */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] 1724 2006-09-05T21:04:15Z DeWitt 2 /* Community */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] 1729 2006-09-05T21:33:44Z DeWitt 2 Protected "[[Home]]" [edit=sysop:move=sysop] __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] 1934 2007-08-11T23:15:16Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension [draft]]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] 1949 2007-11-27T15:40:08Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension [draft]]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch wishlist|Wishlist of ideas for OpenSearch 2]] 1950 2007-11-27T15:40:28Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 3)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension [draft]]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch 2 wishlist|Wishlist of ideas for OpenSearch 2]] 2216 2009-03-23T20:59:34Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 4)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension [draft]]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch 2 wishlist|Wishlist of ideas for OpenSearch 2]] 2343 2009-11-30T15:46:27Z DeWitt 2 /* Specifications */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 4)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] ** [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch 2 wishlist|Wishlist of ideas for OpenSearch 2]] 2556 2011-08-11T15:39:10Z DeWitt 2 /* Specifications */ __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 5)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] ** [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch 2 wishlist|Wishlist of ideas for OpenSearch 2]] 2615 2011-11-04T14:37:54Z DeWitt 2 __NOTOC__ == Introduction == OpenSearch is a collection of simple formats for the sharing of search results. The [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] format can be used to describe a search engine so that it can be used by [[Community/OpenSearch search clients|search client applications]]. The [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to [[Community/OpenSearch search engine directories|return search results]]. == For everyone == * [[Documentation/Frequently asked questions|Frequently asked questions]] * [[Community/OpenSearch search clients|Search clients that support OpenSearch]] * [[Community/OpenSearch search engine directories|Directories of search engines that support OpenSearch]] == For developers == === Specifications === * [[Specifications/OpenSearch/1.1|OpenSearch 1.1 (Draft 5)]] ** [[Specifications/OpenSearch/1.1#OpenSearch_description_document|OpenSearch description document]] ** [[Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax|OpenSearch URL template syntax]] ** [[Specifications/OpenSearch/1.1#OpenSearch_Query_element|OpenSearch Query element]] ** [[Specifications/OpenSearch/1.1#OpenSearch_response_elements|OpenSearch response elements]] * [[Specifications/OpenSearch/Extensions|OpenSearch extensions]] ** [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] ** [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] ** [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] ** [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] ** [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|OpenSearch Geo extension (Draft)]] ** [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] ** [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] * [[Specifications/Archive|Archived specifications]] * [[Specifications/License|License]] * [[Specifications/OpenSearch/Changelog|OpenSearch specification changelog]] === Documentation === * [[Documentation/Developer how to guide|Developer "how to" guide]] * [[Documentation/Developer best practices guide|Developer "best practices" guide]] * [[Documentation/Recommendations/OpenSearch and microformats|OpenSearch and microformats]] * [[Documentation/Stylesheet|OpenSearch response stylesheet]] * [[Documentation/OpenSearch 1.0 to 1.1 upgrade guide|OpenSearch 1.0 to 1.1 upgrade guide]] === Community === * [[Community/OpenSearch software|Software libraries for reading and writing OpenSearch]] * [[Community/Guidelines|Editorial guidelines]] * [[Community/Roadmap|OpenSearch roadmap]] * [[Community/Mailing lists|Mailing lists]] * [[Community/Todo list|Website todo list]] * [[Community/OpenSearch community|People in the community]] * [[Community/OpenSearch 2 wishlist|Wishlist of ideas for OpenSearch 2]] Mailman/listinfo/discuss 1467 1704 2006-09-05T16:36:41Z DeWitt 2 Welcome to the new OpenSearch.org website. If you landed here, it is probably because you followed a link to the old OpenSearch discussion mailing list. We are in the process of migrating the old list over to a new location. The subscribers and archives will be moved automatically, but in the meantime, please feel free to sign up for the new [[Community/Mailing_lists|mailing list]] by hand. 1705 2006-09-05T16:37:06Z DeWitt 2 Welcome to the new OpenSearch.org website. If you landed here, it is probably because you followed a link to the old OpenSearch discussion mailing list. We are in the process of migrating the old list over to a new location. The subscribers and archives will be moved automatically, but in the meantime, please feel free to sign up for the new [[Community/Mailing_lists|mailing list]] by hand. Also, please [[Home|take a look around]], and welcome! Main Page 1 1 2006-07-22T17:13:13Z MediaWiki default <big>'''MediaWiki has been successfully installed.'''</big> Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software. == Getting started == * [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list] * [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] * [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list] 1405 2006-07-22T23:24:44Z DeWitt 2 /* Getting started */ <big>'''MediaWiki has been successfully installed.'''</big> Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software. == Getting started == * [[Test]] * [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list] * [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] * [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list] 1659 2006-08-23T14:40:04Z DeWitt 2 Redirecting to [[Home]] #REDIRECT [[Home]] Roadmap 1464 1694 2006-09-05T14:46:22Z DeWitt 2 [[Roadmap]] moved to [[Community/Roadmap]] #REDIRECT [[Community/Roadmap]] Specifications 1429 1439 2006-07-25T18:07:33Z DeWitt 2 ==Current specifications== * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ==Archived specifications== * [[Specifications/OpenSearch/1.0|OpenSearch 1.0]] 1455 2006-07-25T20:17:36Z DeWitt 2 ==Specifications== * [[Specifications/OpenSearch]] * [[Specifications/OpenSearch/Extensions]] 1460 2006-07-25T23:53:23Z DeWitt 2 /* Specifications */ ==Current Specifications== * [[Specifications/OpenSearch|OpenSearch specification]] * [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]] ==Archived specifications== * [[Specifications/OpenSearch/Archive|Archived OpenSearch specifications]] 1461 2006-07-25T23:53:43Z DeWitt 2 /* Archived specifications */ ==Current Specifications== * [[Specifications/OpenSearch|OpenSearch specification]] * [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]] ==Archived specifications== * [[Specifications/Archive/OpenSearch|Archived OpenSearch specifications]] 1462 2006-07-25T23:54:25Z DeWitt 2 /* Archived specifications */ ==Current Specifications== * [[Specifications/OpenSearch|OpenSearch specification]] * [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]] See also the [[Specifications/Archive|archived specifications]]. Specifications/Archive 1413 1440 2006-07-25T18:10:39Z DeWitt 2 ==Notice== '''The following documents are made available for archival purposes. Please refer to the [[Specifications/OpenSearch/1.1|latest OpenSearch specification]].''' ==Archived specifications== * OpenSearch 1.0 ** [http://opensearch.a9.com/spec/opensearchdescription/1.0/ OpenSearch Description Document] ** [http://opensearch.a9.com/spec/opensearchquerysyntax/1.0/ OpenSearch Query Syntax] ** [http://opensearch.a9.com/spec/opensearchrss/1.0/ OpenSearch RSS] 1441 2006-07-25T18:10:56Z DeWitt 2 [[Specifications/OpenSearch/1.0]] moved to [[Specifications/Archive]] ==Notice== '''The following documents are made available for archival purposes. Please refer to the [[Specifications/OpenSearch/1.1|latest OpenSearch specification]].''' ==Archived specifications== * OpenSearch 1.0 ** [http://opensearch.a9.com/spec/opensearchdescription/1.0/ OpenSearch Description Document] ** [http://opensearch.a9.com/spec/opensearchquerysyntax/1.0/ OpenSearch Query Syntax] ** [http://opensearch.a9.com/spec/opensearchrss/1.0/ OpenSearch RSS] 2220 2009-03-24T02:05:05Z DeWitt 2 ==Notice== '''The following documents are made available for archival purposes. Please refer to the [[Specifications/OpenSearch/1.1|latest OpenSearch specification]].''' ==Archived specifications== * OpenSearch 1.1 ** [http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3 OpenSearch 1.1 Draft 3] * OpenSearch 1.0 ** [http://opensearch.a9.com/spec/opensearchdescription/1.0/ OpenSearch Description Document] ** [http://opensearch.a9.com/spec/opensearchquerysyntax/1.0/ OpenSearch Query Syntax] ** [http://opensearch.a9.com/spec/opensearchrss/1.0/ OpenSearch RSS] Specifications/License 1411 1438 2006-07-25T18:05:24Z DeWitt 2 The [[Specifications|OpenSearch specifications]] and [[Specifications/Extensions|OpenSearch extensions]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License] (the License). 1458 2006-07-25T20:25:37Z DeWitt 2 The [[Specifications|OpenSearch specifications]] and [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License] (the License). 1622 2006-08-10T18:06:13Z RobG 3 The [[Specifications|OpenSearch specifications]] and [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1661 2006-08-25T13:48:00Z DeWitt 2 The [[Specifications|OpenSearch specifications]], [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]], and the [[About OpenSearch.org|OpenSearch.org website]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1662 2006-08-25T13:53:39Z DeWitt 2 Except where otherwise noted, the [[Specifications|OpenSearch specifications]], [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]], and the [[About OpenSearch.org|OpenSearch.org website]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1718 2006-09-05T20:54:50Z DeWitt 2 Protected "[[Specifications/License]]" [edit=sysop:move=sysop] Except where otherwise noted, the [[Specifications|OpenSearch specifications]], [[Specifications/OpenSearch/Extensions|OpenSearch extension specifications]], and the [[About OpenSearch.org|OpenSearch.org website]] are made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. Specifications/OpenSearch 1419 1454 2006-07-25T20:16:50Z DeWitt 2 ==Current specifications== * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] ==Archived specifications== * [[Specifications/OpenSearch/1.0|OpenSearch 1.0]] 1456 2006-07-25T20:19:10Z DeWitt 2 /* Archived specifications */ ==Current specifications== * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] See also [[Specifications/Archive]]. 1459 2006-07-25T23:51:49Z DeWitt 2 /* Current specifications */ ==Current specifications== * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] See also [[Specifications/Archive|the archived OpenSearch specifications]]. 1552 2006-08-09T15:34:56Z DeWitt 2 /* Current specifications */ == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 3]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2219 2009-03-24T02:04:24Z DeWitt 2 /* Core specifications */ == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 3|OpenSearch 1.1 Draft 4]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2221 2009-03-24T02:05:21Z DeWitt 2 == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 4|OpenSearch 1.1 Draft 4]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2437 2010-08-26T13:56:26Z Awnjiboo 980 /* Extension specifications */ www.myspace.com/415543822 == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 4|OpenSearch 1.1 Draft 4]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. www.myspace.com/415543822 == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2438 2010-08-26T13:57:15Z Awnjiboo 980 /* Core specifications */ erased mail == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 4|OpenSearch 1.1 Draft 4]] erased mail == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. www.myspace.com/415543822 == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2439 2010-08-26T14:01:38Z Awnjiboo 980 /* Archived specifications */ www.myspace.com/415543822 == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 4|OpenSearch 1.1 Draft 4]] erased mail == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. www.myspace.com/415543822 == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. www.myspace.com/415543822 2473 2011-03-07T14:20:00Z DeWitt 2 Reverted edits by [[Special:Contributions/Awnjiboo|Awnjiboo]] ([[User talk:Awnjiboo|Talk]]); changed back to last version by [[User:DeWitt|DeWitt]] == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 4|OpenSearch 1.1 Draft 4]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. 2606 2011-10-20T10:34:06Z Xyzzy 262 /* Core specifications */ s/draft 4/draft 5/ == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 5|OpenSearch 1.1 Draft 5]] == Extension specifications == See [[Specifications/OpenSearch/Extensions|the OpenSearch extensions page]]. == Archived specifications == See [[Specifications/Archive|the archived OpenSearch specifications]]. Specifications/OpenSearch/1.0 1414 1442 2006-07-25T18:10:57Z DeWitt 2 [[Specifications/OpenSearch/1.0]] moved to [[Specifications/Archive]] #REDIRECT [[Specifications/Archive]] Specifications/OpenSearch/1.1 1415 1444 2006-07-25T18:20:35Z DeWitt 2 Redirecting to [[Specifications/OpenSearch/1.1/Draft 3]] #REDIRECT [[Specifications/OpenSearch/1.1/Draft 3]] 2215 2009-03-23T20:59:17Z DeWitt 2 Redirecting to [[Specifications/OpenSearch/1.1/Draft 4]] #REDIRECT [[Specifications/OpenSearch/1.1/Draft 4]] 2555 2011-08-11T15:38:59Z DeWitt 2 Redirecting to [[Specifications/OpenSearch/1.1/Draft 5]] #REDIRECT [[Specifications/OpenSearch/1.1/Draft 5]] 2588 2011-09-08T21:30:56Z Mrcarter 1310 Redirecting to [[Specifications/shortname/1.1/Draft 5]] #REDIRECT [[Specifications/shortname/1.1/Draft 5]] 2596 2011-09-25T17:11:35Z DeWitt 2 Reverted edits by [[Special:Contributions/Mrcarter|Mrcarter]] ([[User talk:Mrcarter|Talk]]); changed back to last version by [[User:DeWitt|DeWitt]] #REDIRECT [[Specifications/OpenSearch/1.1/Draft 5]] 2597 2011-09-25T17:12:20Z DeWitt 2 Protected "[[Specifications/OpenSearch/1.1]]" [edit=sysop:move=sysop] #REDIRECT [[Specifications/OpenSearch/1.1/Draft 5]] Specifications/OpenSearch/1.1/Draft 3 1408 1435 2006-07-25T16:08:00Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == This document specifies 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "startIndexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "startPageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1448 2006-07-25T18:24:10Z DeWitt 2 /* The "startPage" parameter */ == Notice == {{Template:Draft notice}} == Overview == This document specifies 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "startIndexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1449 2006-07-25T18:24:23Z DeWitt 2 /* The "startIndex" parameter */ == Notice == {{Template:Draft notice}} == Overview == This document specifies 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1464 2006-08-07T16:27:53Z DeWitt 2 /* Overview */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1543 2006-08-09T14:42:38Z DeWitt 2 Protected "[[Specifications/OpenSearch/1.1/Draft 3]]" [edit=sysop:move=sysop] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1574 2006-08-09T16:26:56Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1595 2006-08-09T17:34:08Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1617 2006-08-09T20:13:24Z DeWitt 2 /* Author */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === Elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1640 2006-08-14T13:59:22Z DeWitt 2 /* Elements */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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 a extended parameter:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1641 2006-08-14T14:11:55Z DeWitt 2 /* Examples */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1642 2006-08-14T14:12:29Z DeWitt 2 /* The "Query" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1643 2006-08-14T14:12:58Z DeWitt 2 /* Local role values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== The number of search results returned per page. : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1644 2006-08-14T14:16:00Z DeWitt 2 /* The "itemsPerPage" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that must be set to true if the content returned by the search engine may not suitable for younger audiences. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1658 2006-08-23T07:17:59Z DeWitt 2 /* The "AdultContent" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== Contains a boolean value that should be set to true if the search results may contain material intended only for adults. : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1680 2006-09-05T13:07:35Z DeWitt 2 /* The "AdultContent" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@a9.com> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1681 2006-09-05T13:07:50Z DeWitt 2 /* Author */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1682 2006-09-05T13:09:02Z DeWitt 2 /* Parameter names */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === The search client '''must''' replace every instance of a template parameter with a value before the search request is performed. ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. Parameter names are case-sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1683 2006-09-05T13:11:42Z DeWitt 2 /* Substitution rules */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace, either implicitly in the case of local paramater names, or explicitly via a parameter name prefix in the case of fully qualified parameter names. Parameter names are case-sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1684 2006-09-05T13:16:43Z DeWitt 2 /* Parameter names */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. Parameter names are case-sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1685 2006-09-05T13:17:59Z DeWitt 2 /* Parameter names */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Local parameter names ==== Local parameter names do not include a parameter name prefix. Local parameter names are associated with the [[#Namespace|OpenSearch 1.1 namespace]]. This specification contains an exhaustive list of all local [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]]. ''Example of a local parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1686 2006-09-05T14:10:09Z DeWitt 2 /* Local parameter names */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ XML namespace] prefix on the containing element or ancestor elements. ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1687 2006-09-05T14:18:14Z DeWitt 2 /* Parameter name prefix */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== Fully qualified parameter names include a parameter name prefix. Fully qualified parameter names are associated with the namespace identified by the prefix on the containing element or ancestor elements. ''Example of a fully qualified parameter name:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1688 2006-09-05T14:21:20Z DeWitt 2 /* Fully qualified parameter names */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === The following parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the parameter names listed below may appear in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1689 2006-09-05T14:22:28Z DeWitt 2 /* OpenSearch 1.1 parameters */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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 in the OpenSearch 1.1 namespace. Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1690 2006-09-05T14:22:54Z DeWitt 2 /* OpenSearch 1.1 parameters */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title=Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1727 2006-09-05T21:19:53Z DeWitt 2 /* Autodiscovery in RSS/Atom */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|OpenSearch Query element]] specification for more information. ''OpenSearch description documents should include at least one Query element of type="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 1890 2006-11-27T15:59:41Z DeWitt 2 Fixed a non-normative typo in the contextual documentation. == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] Specifications/OpenSearch/1.1/Draft 4 1676 2089 2008-10-01T19:23:39Z DeWitt 2 Initial version of the Draft 4 spec. Right now it is just a clone of Draft 3. To be used as a jumping off point. == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a search client can make search requests of the search engine. ''OpenSearch provides support for both index-based and page-based search engines. By default, both the first search result and the first page of search results are numbered "1". Search engines can use the "indexOffset" and "pageOffset" attributes to inform search clients of different starting values.'' : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - Contains the search URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - Contains the MIME type of the search result format. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>indexOffset</code> - Contains the index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - Contains the page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1". ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing the interface used to retrieve search results over RSS:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing the interface used to retrieve 0-based search results over XHTML:'' <Url type="application/xhtml+xml" indexOffset="0" template="<nowiki>http://example.com/search?q={searchTerms}&amp;start={startIndex?}</nowiki>" /> ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2176 2008-12-05T18:51:55Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or other description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Rel values|rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Rel values ===== ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2177 2008-12-05T18:53:58Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Rel values|rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Rel values ===== ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2178 2008-12-05T19:27:02Z DeWitt 2 /* Rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Rel values|rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt valid URL]. The semantic meaning of any fully qualified token is outside the scope of this specification. All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those unqualified tokens listed below have semantic meaning defined by this specification. Rel values: : <code>"search"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents a the canonical URL for this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2179 2008-12-05T19:27:36Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt valid URL]. The semantic meaning of any fully qualified token is outside the scope of this specification. All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those unqualified tokens listed below have semantic meaning defined by this specification. Rel values: : <code>"search"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents a the canonical URL for this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2180 2008-12-05T19:28:19Z DeWitt 2 /* Url rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt valid URL]. The semantic meaning of any fully qualified token is outside the scope of this specification. All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those unqualified tokens listed below have semantic meaning defined by this specification. Rel values: : <code>"search"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL for this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2181 2008-12-05T19:30:25Z DeWitt 2 /* Url rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a query used to return page-based search results as a HTML page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''Example of a Url element describing a query used to retrieve indexed-based (starting at 0) search results over RSS:'' <Url type="application/rss+xml" indexOffset="0" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a query used to retrieve search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a query used to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt valid URL]. The semantic meaning of any fully qualified token is outside the scope of this specification. All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those unqualified tokens listed below have semantic meaning defined by this specification. Rel values: : <code>"search"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2182 2008-12-05T19:35:17Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "search" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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" template="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/x-suggestions+json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"search"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2183 2008-12-05T20:40:21Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggetions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2184 2008-12-05T20:44:08Z DeWitt 2 /* Url rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "search"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2185 2008-12-05T21:28:35Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute string 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2186 2008-12-05T21:29:30Z DeWitt 2 /* Url rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2217 2009-03-23T21:08:46Z DeWitt 2 /* Url rel values */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2241 2009-08-05T00:29:38Z Gerson 706 /* Examples */ xyz == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2251 2009-09-15T02:27:15Z Mayajowo 744 /* Namespace */ mayajowo == Notice == {{Template:Draft notice}} == Overview == 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.'' ==.mayajowo == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2252 2009-09-15T02:31:33Z Mayajowo 744 /* Notice */ == Catatatan == {{Template:Draft notice}} == Overview == 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.'' ==.mayajowo == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2253 2009-09-15T02:31:47Z Mayajowo 744 /* Catatatan */ == Catatan == {{Template:Draft notice}} == Overview == 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.'' ==.mayajowo == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2254 2009-09-15T02:32:26Z Mayajowo 744 /* Overview */ == Catatan == {{Template:Draft notice}} == Lihat Sebentar == 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.'' ==.mayajowo == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2255 2009-09-15T02:33:03Z Mayajowo 744 /* Examples */ contoh == Catatan == {{Template:Draft notice}} == Lihat Sebentar == 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.'' ==.mayajowo == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === CONTOH === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2259 2009-09-16T16:03:56Z DeWitt 2 Reverted edits by [[Special:Contributions/Mayajowo|Mayajowo]] ([[User talk:Mayajowo|Talk]]); changed back to last version by [[User:Gerson|Gerson]] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> </copyright:gerson chicareli 2009 === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2260 2009-09-16T16:06:36Z DeWitt 2 Rollback spam edits == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2261 2009-09-16T16:07:41Z DeWitt 2 Protected "[[Specifications/OpenSearch/1.1/Draft 4]]" [edit=sysop:move=sysop] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 chose 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2313 2009-11-10T18:17:17Z DeWitt 2 /* The "Image" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2416 2010-05-23T22:23:08Z DeWitt 2 /* The "Url" element */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] Specifications/OpenSearch/1.1/Draft 5 1821 2475 2011-03-11T18:57:34Z DeWitt 2 Seed Draft 5 with an exact copy of Draft 4. == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 3066. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2476 2011-03-11T18:59:33Z DeWitt 2 Update references to the obsolete RFC 3066 to point to the current RFC 5646. == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2494 2011-03-12T00:28:58Z DeWitt 2 Unprotected "[[Specifications/OpenSearch/1.1/Draft 5]]" == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2600 2011-10-18T02:03:10Z Xyzzy 262 /* Autodiscovery */ Plan B: No RFC, do it yourself == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2601 2011-10-18T02:18:54Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ insert template from expired Internet draft == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. <pre> 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 OpenSearch descriptions. Security considerations: All general security and privacy considerations for sending queries to servers specified in an URL are applicable. TBD Interoperability considerations: OpenSearch descriptions use the <http://a9.com/-/spec/opensearch/1.1/> XML name space, optionally in conjunction with other XML name spaces for extensions or for application specific purposes. Published specification: <http://www.opensearch.org/Specifications/OpenSearch/1.1> Applications that use this media type: Various search cients including popular Web browsers, search engines, and software libraries support OpenSearch descriptions. Additional information: TBD Person & email address to contact for further information: TBD Intended usage: COMMON Restrictions on usage: None Author: Clinton DeWitt Change controller: <http://www.opensearch.org/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2602 2011-10-18T02:44:12Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ work in progress == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. <pre> 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 OpenSearch descriptions. Security considerations: All general security and privacy considerations for sending queries to servers specified in an URL are applicable. TBD Interoperability considerations: OpenSearch descriptions use the <http://a9.com/-/spec/opensearch/1.1/> XML name space, optionally in conjunction with other XML name spaces for extensions or for 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 OpenSearch Description Documents. The Ecmascript API AddSearchProvider() documented for WhatWG HTML uses this media type. The RFC .... link relation "search" is typically used in conjunction with this media type. Additional information: TBD Person & email address to contact for further information: <http://groups.google.com/group/opensearch> Intended usage: COMMON Restrictions on usage: None Author: Clinton DeWitt Change controller: <http://www.opensearch.org/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2603 2011-10-18T03:54:16Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ filled in some gaps == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. <pre> 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 OpenSearch descriptions. 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 OpenSearch Description Documents (OSSD) it affects the privacy of users. The Ecmascript API AddSearchProvider() typically enforces a "same origin" policy. An OSDD can claim to be a search description for X, but actually do something else. Interoperability considerations: OSDDs 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 OSDDs. 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: OSDDs have no "magic numbers" as specified in RFC 4288. There are no special "common file name extensions" for OSDDs, OSDDs are XML documents. If specific extensions are desired ".a9.xml" (or similar) 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/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2604 2011-10-18T04:01:29Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ Define OSDD a.s.a.p. == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. <pre> 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 OSDD (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 OSDDs it affects the privacy of users. The Ecmascript API AddSearchProvider() typically enforces a "same origin" policy. An OSDD can claim to be a search description for X, but actually do something else. Interoperability considerations: OSDDs 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 OSDDs. 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: OSDDs have no "magic numbers" as defined in RFC 4288. There are no special "common file name extensions" for OSDDs, OSDDs are XML documents. If specific extensions are desired ".a9.xml" (or similar) 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/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2605 2011-10-20T10:30:49Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ Copy "pending registration" disclaimer from [[#Type]] section == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <pre> 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 OSDD (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 OSDDs it affects the privacy of users. The Ecmascript API AddSearchProvider() typically enforces a "same origin" policy. An OSDD can claim to be a search description for X, but actually do something else. Interoperability considerations: OSDDs 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 OSDDs. 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: OSDDs have no "magic numbers" as defined in RFC 4288. There are no special "common file name extensions" for OSDDs, OSDDs are XML documents. If specific extensions are desired ".a9.xml" (or similar) 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/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2607 2011-10-20T10:41:13Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ improve "same origin" security consideration == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <pre> 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 OSDD (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 OSDDs it affects the privacy of users. The Ecmascript API AddSearchProvider() typically enforces a "same origin" policy for the OSDD; the URL element within the OSDD can designate a third party as search provider. An OSDD can claim to be a search description for X, but actually do something else. Interoperability considerations: OSDDs 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 OSDDs. 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: OSDDs have no "magic numbers" as defined in RFC 4288. There are no special "common file name extensions" for OSDDs, OSDDs are XML documents. If specific extensions are desired ".a9.xml" (or similar) 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/> </pre> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2609 2011-10-20T12:12:58Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ font-size: smaller == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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 OSDD (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 OSDDs it affects the privacy of users. The Ecmascript API AddSearchProvider() typically enforces a "same origin" policy for the OSDD; the URL element within the OSDD can designate a third party as search provider. An OSDD can claim to be a search description for X, but actually do something else. Interoperability considerations: OSDDs 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 OSDDs. 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: OSDDs have no "magic numbers" as defined in RFC 4288. There are no special "common file name extensions" for OSDDs, OSDDs are XML documents. If specific extensions are desired ".a9.xml" (or similar) 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2610 2011-10-20T12:18:14Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ s/OSDD/OSD/g and added ".osdx" == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2611 2011-10-20T12:19:28Z Xyzzy 262 /* MIME type application/opensearchdescription+xml */ blank line before text/xml blurb == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2637 2011-12-03T17:59:07Z Alroeyanews 1449 /* Examples */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <ShortName>الرؤية الإخبارية</ShortName> <Description>alroeya-news.net to search the Web.</Description> <Tags> الرؤية الإخبارية</Tags> <Contact>sallam.awad@gmail.com</Contact> <Url type="application/rss+xml" template="<nowiki>http://alroeya-news.net/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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>ar-sa</Language> <OutputEncoding>UTF-8</OutputEncoding> <InputEncoding>UTF-8</InputEncoding> </OpenSearchDescription> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2640 2011-12-04T05:37:13Z Xyzzy 262 Reverted edits by [[Special:Contributions/Alroeyanews|Alroeyanews]] ([[User talk:Alroeyanews|Talk]]); changed back to last version by [[User:Xyzzy|Xyzzy]] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2771 2012-03-11T19:27:02Z Ajaytiwari 1648 /* Elements */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2979 2012-07-07T05:08:27Z Jgjc 1908 /* Examples */ == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. == Core specifications == * [[Specifications/OpenSearch/1.1/Draft 5|OpenSearch 1.1 Draft 5]] <html> <head> <title>_.-حـ]ٍآٍآكمٍ الٍلٍه بٍـدٍردٍشةٍ قٍـٍلٍوٍبٍ الـــٍصوتٍـيٍه-._</title> <meta http-equiv="Content-Type" content="text/html; charset=WINDOWS-1256"> <link rel="stylesheet" href="/inc/bmc.css" type="text/css"> </head> <script Language="JavaScript"> // var hostpath, URL; hostpath = window.location.host; if (hostpath.lastIndexOf(":") >= 0) hostpath = hostpath.substring(0, hostpath.lastIndexOf(":")); hostpath = hostpath + window.location.pathname; hostpath = "http://" + hostpath.substring(0, hostpath.lastIndexOf("\/") + 1); var plugInCounter, bBMChatPlugin; var Sys = {}; var ua = navigator.userAgent.toLowerCase(); var s; (s = ua.match(/msie ([\d.]+)/)) ? Sys.ie = s[1] : (s = ua.match(/firefox\/([\d.]+)/)) ? Sys.firefox = s[1] : (s = ua.match(/chrome\/([\d.]+)/)) ? Sys.chrome = s[1] : (s = ua.match(/opera.([\d.]+)/)) ? Sys.opera = s[1] : (s = ua.match(/version\/([\d.]+).*safari/)) ? Sys.safari = s[1] : 0; if( !Sys.ie && !Sys.firefox && !Sys.chrome && !Sys.opera && !Sys.safari ){ window.location.href = "/inc/unsupported_browser_small.htm"; } if (!Sys.ie) { var plugInCounter; bBMChatPlugin = 0; for (plugInCounter = 0; plugInCounter < navigator.plugins.length; plugInCounter++) { if (navigator.plugins[plugInCounter].name.indexOf("BMChat") >= 0) { bBMChatPlugin = 1; break; } } } else bBMChatPlugin = 1; function _login() // { var trimmeduid; trimmeduid = document.form1.uid.value.replace(/(^\s*)|(\s*$)/g, ""); if (document.form1.uid.value.length == 0) { alert("من فضلك اكتب اسمك أولا حتى تستطيع الدخول ثم اضغط على كلمة الدخول بالماوس"); document.form1.uid.focus(); return; } if (document.form1.uid.value.length >= 50) { alert("Invalid Nick name for length"); document.form1.uid.focus(); return; } if (trimmeduid == "") { alert("من فضلك اكتب اسمك أولا حتى تستطيع الدخول ثم اضغط على كلمة الدخول بالماوس"); document.form1.uid.focus(); return; } if (document.form1.uid.value.indexOf("@@") != -1 || document.form1.uid.value.indexOf("&") != -1 || document.form1.uid.value.indexOf("%") != -1 || document.form1.uid.value.indexOf("+") != -1) { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } if (document.form1.uid.value.indexOf("#") != -1 || document.form1.uid.value.indexOf("*") != -1 || document.form1.uid.value.indexOf("~") != -1) { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } if (trimmeduid.substring(0, 1) == "." || trimmeduid.substring(0, 1) == "~" || trimmeduid.substring(0, 1) == ":") { alert("عفوا, ان الاسم اللذى قمت بادخاله غير مقبول قد يكون أقل من حرفين أو به رموز غير مقبوله أو مخفى"); document.form1.uid.focus(); return; } url = "voicechat.htm?uid=" + document.form1.uid.value; if (document.form1.iBrowser.value == 2) { var bRet; bRet = false; try { if (Sys.ie) { var ILObj; ILObj = new ActiveXObject("ILBMChat.Launcher"); bRet = ILObj.LaunchBMChat("174.37.31.175", 1990, "qloob2", 0, document.form1.uid.value, "", "C25A7C" + "ffbfbf", 1256); } else { if (bBMChatPlugin) { BMChatObj = document.getElementById("NPBMChat"); bRet = BMChatObj.Launch("174.37.31.175", 1990, "qloob2", 0, document.form1.uid.value, "", "C25A7C" + "ffbfbf", 1256); } } } catch (e) { bRet = false; } if (!bBMChatPlugin || !bRet) { if (confirm("ان برنامج نايل فويس لم يتم تحميله فى جهازك حتى الآن, هل تريد التحميل الآن؟؟")) window.open("http://174.37.31.175/inc/download.htm", ""); } } else { if (window.open(url, "", "width=788, height=544, left=0, top=0, resizable=yes, status=yes, location=no, directories=no, menubar=no, scrollbars=no") == null) alert("Prompt window blocked, please close the windows blocker and try again."); } } function getcolor() { if (Sys.ie) window.open ("iecolor.htm", "", "height=260,width=500,status=no,toolbar=no,menubar=no,location=no"); else window.open ("color.htm", "", "height=260,width=500,status=no,toolbar=no,menubar=no,location=no"); } // by zhangxinxu welcome to visit my personal website http://www.zhangxinxu.com/ var reg = /^#([0-9a-fA-f]{3}|[0-9a-fA-f]{6})$/; String.prototype.colorHex = function(){ var that = this; if(/^(rgb|RGB)/.test(that)){ var aColor = that.replace(/(?:\(|\)|rgb|RGB)*/g,"").split(","); var strHex = "#"; for(var i=0; i<aColor.length; i++){ var hex = Number(aColor[i]).toString(16); if(hex === "0"){ hex += hex; } strHex += hex; } if(strHex.length !== 7){ strHex = that; } return strHex; }else if(reg.test(that)){ var aNum = that.replace(/#/,"").split(""); if(aNum.length === 6){ return that; }else if(aNum.length === 3){ var numHex; for(var i=0; i<aNum.length; i+=1){ numHex += (aNum[i]+aNum[i]); } return numHex; } }else{ return that; } }; </Script> <body style="font-family: Verdana; font-size: 10px; color: #000000" leftmargin="0" topmargin="0" link="#666666" vlink="#666666" alink="#666666"> <form name="form1"> <table width="100%" height="100%" border="0" align="center" cellpadding="0" cellspacing="0" background="http://www9.0zz0.com/2012/05/14/16/496731378.gif" bgcolor="#DF3F5F"> <tr> <TD> <div id="tabchg" align="center"> <TABLE border=0 cellPadding=0 cellSpacing=0 height=60 width="100%" style="border-collapse: collapse" bordercolor="#111111"> <TR> <TD align=middle> <font face="Tahoma" color="#FF005F"> ادخل اسمك هنا</font></TD> </tr> <TR> <TD align="center" height="30"><font face="Tahoma"> <input maxlength="45" id="uid" name="uid" size="20" style="border-style:inset; border-width:1; BACKGROUND-COLOR: #FFFFFF; FONT-SIZE: 9pt; text-align:center; color:#FF0033" value="" tabindex="1" onkeypress="if(event.keyCode==13){_login();return false;}" enabled> </font></TD> </TR> <TR id="trbrowser" name="trbrowser" style="display:none"> <TD align="center" height="25"> <select name="iBrowser" style="border-style:outset; border-width:1px; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; FONT-SIZE: 12px;" tabindex="4"> <option value="1" style="background:#C25A7C; COLOR: #FF005F" selected>Internet Explorer</option> <option value="2" style="background:#C25A7C; COLOR: #FF005F">BMChat Application</option> </select></TD> </TR> <TR> <TD align="center" height="25"> <div align="center"> <INPUT class="form" name="btgo" type="button" value="الدخول" onClick="_login();return false" style="width:65px; border-style:outset; border-width:1px; background:#FF3F7F; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; COLOR: #FF003F; FONT-SIZE: 12px; " tabindex="2" enabled> <input class="form" name="btmember" type="button" value="دخول الأكواد" onClick="window.location.href=hostpath+'default1.asp?style=1';return(false)" style="width:65px; border-style:outset; border-width:1px; background:#FF0000; BORDER-DOWN: 1px solid; FONT-FAMILY: Tahoma; COLOR: #FFFFFF; FONT-SIZE: 12px; " tabindex="3"> </div></TD> </TR> </TABLE> </div></TD> </tr> </table></td> </tr> </table> </form> <script Language="JavaScript"> if (!Sys.ie) { if (bBMChatPlugin) document.write ("<embed id=\"NPBMChat\" type=\"application/x-npbmchat\" width=\"0\", height=\"0\">"); for (i = 0; i < document.form1.iBrowser.length; i++) { if (document.form1.iBrowser.options[i].value == 2) { document.form1.iBrowser.selectedIndex = i; break; } } document.getElementById("trbrowser").style.display="none"; } </script> </body> </html> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2994 2012-07-10T23:11:07Z DeWitt 2 Reverted edits by [[Special:Contributions/Jgjc|Jgjc]] ([[User talk:Jgjc|Talk]]); changed back to last version by [[User:Ajaytiwari|Ajaytiwari]] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] 2995 2012-07-10T23:13:34Z DeWitt 2 Protected "[[Specifications/OpenSearch/1.1/Draft 5]]" [edit=sysop:move=sysop] == Notice == {{Template:Draft notice}} == Overview == 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.'' == Namespace == The XML Namespaces URI for the XML data formats described in this specification is: : <code><nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki></code> == OpenSearch description document == === Overview === An OpenSearch description document can be used to describe the web interface of a search engine. === Examples === ''Example of a simple OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> </OpenSearchDescription> ''Example of a detailed OpenSearch description document:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&amp;pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png"><nowiki>http://example.com/websearch.png</nowiki></Image> <Image height="16" width="16" type="image/vnd.microsoft.icon"><nowiki>http://example.com/websearch.ico</nowiki></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> === Type === OpenSearch description documents are referred to via the following type: : <code><nowiki>application/opensearchdescription+xml</nowiki></code> ''This type is pending IANA registration.'' === Extensibility === 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. === OpenSearch description elements === ==== The "OpenSearchDescription" element ==== The root node of the OpenSearch description document. : Parent: None : Requirements: The element '''must''' appear exactly once as the root node of the document. ''Example:'' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki> <!--- ... ---></nowiki> </OpenSearchDescription> ==== The "ShortName" element ==== Contains a brief human-readable title that identifies this search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <ShortName>Web Search</ShortName> ==== The "Description" element ==== Contains a human-readable text description of the search engine. : Parent: OpenSearchDescription : Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element '''must''' appear exactly once. ''Example:'' <Description>Use Example.com to search the Web.</Description> ==== The "Url" element ==== Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents. : Parent: OpenSearchDescription : Attributes: :: <code>template</code> - The URL template to be processed according to the [[#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Requirements: This attribute is '''required'''. :: <code>type</code> - The MIME type of the resource being described. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is '''required'''. :: <code>rel</code> - The role of the resource being described in relation to the description document. ::: Restrictions: Contains a space-delimited list of valid rel value tokens. See the [[#Url rel values|Url rel values]] specification for allowed rel values. ::: Default: "results" ::: Requirements: This attribute is optional. :: <code>indexOffset</code> - The index number of the first search result. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pageOffset</code> - The page number of the first set of search results. ::: Restrictions: The value must be an integer. ::: Default: "1" ::: Requirements: This attribute is optional. : Requirements: This element '''must''' appear one or more times. ''Example of a Url element describing a request for a HTML search results page:'' <Url type="text/html" template="<nowiki>http://example.com/search?q={searchTerms}&amp;pw={startPage?}</nowiki>" /> ''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="<nowiki>http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss</nowiki>" /> ''Example of a Url element describing a request for search suggestions over JSON:'' <Url type="application/json" rel="suggestions" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>" /> ''Example of a Url element describing a request to refresh the OpenSearch description document itself:'' <Url type="application/opensearchdescription+xml" rel="self" template="<nowiki>http://example.com/osd.xml</nowiki>" /> ===== Url rel values ===== 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., "<nowiki>http://example.com/rel#foo</nowiki>") or unqualified tokens (e.g., "results"). All fully qualified tokens must be a [http://www.ietf.org/rfc/rfc1738.txt 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: : <code>"results"</code> (default) :: Represents a request for search results in the specified format. : <code>"suggestions"</code> :: Represents a request for search suggestions in the specified format. See the [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] for further details. : <code>"self"</code> :: Represents the canonical URL of this description document. : <code>"collection"</code> :: Represents a request for a set of resources. ==== The "Contact" element ==== Contains an email address at which the maintainer of the description document can be reached. : Parent: OpenSearchDescription : Restrictions: The value must conform to the requirements of Section 3.4.1 "Addr-spec specification" in RFC 2822. : Requirements: This element may appear zero or one time. ''Example:'' <Contact>admin@example.com</Contact> ==== The "Tags" element ==== 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 (' '). : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Tags>example web</Tags> ==== The "LongName" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 48 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <LongName>Example.com Web Search</LongName> ==== The "Image" element ==== 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 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]) and a 64x64 image of type "image/jpeg" or "image/png".'' : Parent: OpenSearchDescription : Attributes: :: <code>height</code> – Contains the height, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>width</code> – Contains the width, in pixels, of this image. ::: Restrictions: The value must be a non-negative integer. ::: Requirements: This attribute is optional. :: <code>type</code> – Contains the the MIME type of this image. ::: Restrictions: The value must be a valid MIME type. ::: Requirements: This attribute is optional. : Restrictions: The value must be a URI. : Requirements: This element may appear zero, one, or more times. ''Example:'' <Image height="16" width="16" type="image/x-icon"<nowiki>>http://example.com/favicon.ico</nowiki></Image> <Image height="64" width="64" type="image/png"<nowiki>>http://example.com/websearch.png</nowiki></Image> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Parent: OpenSearchDescription : Requirements: This element may appear zero or more times. ''Example:'' <Query role="example" searchTerms="cat" /> ==== The "Developer" element ==== 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.'' : Parent: OpenSearchDescription : Restrictions: The value must contain 64 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Developer>Example.com Development Team</Developer> ==== The "Attribution" element ==== Contains a list of all sources or entities that should be credited for the content contained in the search feed. : Parent: OpenSearchDescription : Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. : Requirements: This element may appear zero or one time. ''Example:'' <Attribution>Search data copyright Example.com, Inc.</Attribution> ==== The "SyndicationRight" element ==== Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed. : Parent: OpenSearchDescription : Values: The value must be one of the following strings (case insensitive): :: <code>"open"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may send the search results to other search clients. :: <code>"limited"</code> – ::: The search client may request search results. ::: The search client may display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"private"</code> – ::: The search client may request search results. ::: The search client may not display the search results to end users. ::: The search client may not send the search results to other search clients. :: <code>"closed"</code> - ::: The search client may not request search results. : Default: "open" : Requirements: This element may appear zero or one time. ''Example:'' <SyndicationRight>open</SyndicationRight> ==== The "AdultContent" element ==== 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.'' : Parent: OpenSearchDescription : Values: :: The values "false", "FALSE", "0", "no", and "NO" will be considered boolean FALSE; all other strings will be considered boolean TRUE. : Default: "false" : Requirements: This element may appear zero or one time. ''Example:'' <AdultContent>false</AdultContent> ==== The "Language" element ==== Contains a string that indicates that the search engine supports search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, the value of "*" will signify that the search engine does not restrict search results to any particular language. : Default: "*". : Requirements: This element may appear zero, one, or more times. ''Example:'' <Language>en-us</Language> <Language>*</Language> ==== The "InputEncoding" element ==== Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <InputEncoding>UTF-8</InputEncoding> ==== The "OutputEncoding" element ==== Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Parent: OpenSearchDescription : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8". : Requirements: This element may appear zero, one, or more times. ''Example:'' <OutputEncoding>UTF-8</OutputEncoding> === Autodiscovery === ''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.'' ==== Autodiscovery in RSS/Atom ==== RSS and Atom documents may reference related [[#OpenSearch description document|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: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. ''Example of Atom-based search results that include an OpenSearch autodiscovery link element:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!-- ... ---></nowiki> <link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!-- ... ---></nowiki> </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="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <nowiki><!--- ... ---></nowiki> <atom:link rel="search" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" type="application/opensearchdescription+xml" title="Content Search" /> <nowiki><!--- ... ---></nowiki> </channel> </rss> ==== Autodiscovery in HTML/XHTML ==== HTML and XHTML documents may reference related [[#OpenSearch description document|OpenSearch description documents]] via the [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.3 HTML 4.0 <link/> element]. The following restrictions apply: * The "type" attribute must contain the value "application/opensearchdescription+xml". * The "rel" attribute must contain the value "search". * The "href" attribute must contain a URI that resolves to an OpenSearch description document. * The "title" attribute may contain a human-readable plain text string describing the search engine. * The HTML <head/> element should include a "profile" attribute that contains the value "<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>". ''Example of an HTML document that includes OpenSearch autodiscovery link elements:'' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en" dir="ltr"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/content-search.xml</nowiki>" title="Content search" /> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/comment-search.xml</nowiki>" title="Comments search" /> <nowiki><!--- ... ---></nowiki> </head> <body> <nowiki><!--- ... ---></nowiki> </body> </html> ==== MIME type application/opensearchdescription+xml ==== For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type <code>application/opensearchdescription+xml</code>. ''This type is pending IANA registration.'' <div style="width: 40em"><pre width="78" style="font-size: smaller"> 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/> </pre></div> == OpenSearch URL template syntax == === Overview === 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 <code>{name}</code>, 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.'' === Examples === ''Example of a search URL template that contains a template parameter:'' <nowiki>http://example.com/search?q={searchTerms}</nowiki> ''Example of a search URL template that contains an optional template parameter:'' <nowiki>http://example.com/feed/{startPage?}</nowiki> ''Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a [[#The "Url" element|Url element]]:'' <Url type="application/rss+xml" xmlns:example="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?q={searchTerms}&amp;c={example:color?}</nowiki>"/> === Context === This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the [[#The "Url" element|"Url" element]] in an [[#OpenSearch description document|OpenSearch description document]]. === Template grammar === 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 ) === Substitution rules === 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|optional template parameters]] should be used.'' ==== Parameter names ==== 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. ==== Case sensitivity of parameter names ==== Both the parameter name prefix and the local parameter name are case sensitive. ==== Parameter name prefix ==== A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an [http://www.w3.org/TR/REC-xml-names/ 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="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={a:localname?}</nowiki>"/> <Url type="application/rss+xml" xmlns:b="<nowiki>http://example.com/extensions/</nowiki>" template="<nowiki>http://example.com?q={b:localname?}</nowiki>"/> ==== Unqualified parameter names ==== 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 [[#Namespace|OpenSearch 1.1 namespace]]. ''This specification includes an exhaustive list of all unqualified [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter names]].'' ''Example of an unqualified parameter name:'' <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}</nowiki>"/> ==== Fully qualified parameter names ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" template="<nowiki>http://example.com?f={example:format?}</nowiki>"/> ==== Required template parameters ==== 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 ==== 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?} === OpenSearch 1.1 parameters === 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. ==== The "searchTerms" parameter ==== Replaced with the keyword or keywords desired by the search client. : Restrictions: The value must be URL-encoded. ==== The "count" parameter ==== 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" element|the "itemsPerPage" response element]] in calculating actual page size.'' : Restrictions: The value must be a non-negative integer. ==== The "startIndex" parameter ==== Replaced with the index of the first search result desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "indexOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "startPage" parameter ==== Replaced with the page number of the set of search results desired by the search client. : Restrictions: The value must be an integer. : Default: The value specified by the "pageOffset" attribute of the containing [[#The "Url" element|Url element]]. ==== The "language" parameter ==== Replaced with a string that indicates that the search client desires search results in the specified language. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "Language" element|"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 [[#The "language" parameter|"language" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose among the available languages.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#sec-lang-tag XML 1.0 Language Identification], as specified by RFC 5646. In addition, a value of "*" will signify that the search client desires search results in any language. : Default: "*" ==== The "inputEncoding" parameter ==== 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|OpenSearch description document]] should include one [[#The "InputEncoding" element|"InputEncoding" element]] for each character encoding that can be used to encode search requests. The [[#The "inputEncoding" parameter|"inputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to require the search client to identify which encoding is being used to encode the current search request.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" ==== The "outputEncoding" parameter ==== Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding. ''An [[#OpenSearch description document|OpenSearch description document]] should include one [[#The "OutputEncoding" element|"OutputEncoding" element]] for each character encoding that can be used to encode search responses. The [[#The "outputEncoding" parameter|"outputEncoding" template parameter]] in the [[#OpenSearch URL template|OpenSearch URL template]] can be used to allow the search client to choose a character encoding in the search response.'' : Restrictions: The value must conform to the [http://www.w3.org/TR/2004/REC-xml-20040204/#charencoding XML 1.0 Character Encodings], as specified by the [http://www.iana.org/assignments/character-sets IANA Character Set Assignments]. : Default: "UTF-8" == OpenSearch Query element == === Overview === 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.'' === Examples === ''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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="example" searchTerms="cat" custom:color="blue" title="Sample search" /> ''Example of a Query element using a extended role:'' <Query xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" 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="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <nowiki><!--- ... ---></nowiki> <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" /> <nowiki><!-- ... --></nowiki> </feed> === The "Query" element === Describes a specific search request that can be made by the search client. : Attributes: :: <code>role</code> - Contains a string identifying how the search client should interpret the search request defined by this Query element. ::: Restrictions: See the [[#Role values|role values]] specification for allowed role values. ::: Requirements: This attribute is '''required'''. :: <code>title</code> - Contains a human-readable plain text string describing the search request. ::: Restrictions: The value must contain 256 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This attribute is optional. :: <code>totalResults</code> - Contains the expected number of results to be found if the search request were made. ::: Restrictions: The value is a non-negative integer. ::: Requirements: This attribute is optional. :: <code>searchTerms</code> - Contains the value representing the "searchTerms" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "searchTerms" parameter|"searchTerms" parameter]]. ::: Requirements: This attribute is optional. :: <code>count</code> - Contains the value representing the "count" as a [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "count" parameter|"count" parameter]]. ::: Requirements: This attribute is optional. :: <code>startIndex</code> - Contains the value representing the "startIndex" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startIndex" parameter|"startIndex" parameter]]. ::: Requirements: This attribute is optional. :: <code>startPage</code> - Contains the value representing the "startPage" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "startPage" parameter|"startPage" parameter]]. ::: Requirements: This attribute is optional. :: <code>language</code> - Contains the value representing the "language" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "language" parameter|"language" parameter]]. ::: Requirements: This attribute is optional. :: <code>inputEncoding</code> - Contains the value representing the "inputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "inputEncoding" parameter|"inputEncoding" parameter]]. ::: Requirements: This attribute is optional. :: <code>outputEncoding</code> - Contains the value representing the "outputEncoding" as an [[#OpenSearch 1.1 parameters|OpenSearch 1.1 parameter]]. ::: Restrictions: See the [[#The "outputEncoding" parameter|"outputEncoding" parameter]]. ::: Requirements: This attribute is optional. ''Example:'' <Query role="example" searchTerms="cat" /> === Query element extensibility === 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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com/search?color={custom:color?}</nowiki>" /> <Query role="example" custom:color="blue" /> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Role values === 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. ==== Role extensibility ==== 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. ==== Role prefix ==== 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 ==== Local role values are not preceded by a prefix. Local role values are associated with the [[#Namespace|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: : <code>"request"</code> :: Represents the search query that can be performed to retrieve the same set of search results. : <code>"example"</code> :: Represents a search query that can be performed to demonstrate the search engine. : <code>"related"</code> :: Represents a search query that can be performed to retrieve similar but different search results. : <code>"correction"</code> :: Represents a search query that can be performed to improve the result set, such as with a spelling correction. : <code>"subset"</code> :: Represents a search query that will narrow the current set of search results. : <code>"superset"</code> :: Represents a search query that will broaden the current set of search results. ''Example of a local role value:'' <Query role="related" title="A related search" searchTerms="tiger" /> ==== Fully qualified role values ==== 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="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" role="custom:synonym" title="Synonyms of 'cat'" searchTerms="feline" /> == OpenSearch response elements == 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.'' === Examples of OpenSearch responses === ==== Example of OpenSearch response elements in RSS 2.0 ==== ''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="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>"> <channel> <title>Example.com Search: New York history</title> <link><nowiki>http://example.com/New+York+history</nowiki></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="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <opensearch:Query role="request" searchTerms="New York History" startPage="1" /> <item> <title>New York History</title> <link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></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 OpenSearch response elements in Atom 1.0 ==== ''Example of a page of search results in the Atom 1.0 format:'' <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="<nowiki>http://example.com/New+York+History?pw=3</nowiki>" type="text/html"/> <link rel="self" href="<nowiki>http://example.com/New+York+History?pw=3&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="first" href="<nowiki>http://example.com/New+York+History?pw=1&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="previous" href="<nowiki>http://example.com/New+York+History?pw=2&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="next" href="<nowiki>http://example.com/New+York+History?pw=4&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="last" href="<nowiki>http://example.com/New+York+History?pw=42299&amp;format=atom</nowiki>" type="application/atom+xml"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <!-- 9 additional <entry> elements appear here --> </feed> === Elements === ==== The "totalResults" element ==== 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.'' : Restrictions: The value must be a non-negative integer. : Default: The default value is equal to the offset index of the last search result on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <totalResults>492420</totalResults> ==== The "startIndex" element ==== 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.'' : Restrictions: The value must an integer. : Default: The default value is equal to the value of the "indexOffset" attribute of the [[#The "Url" element|"Url" element"]] in the [[#OpenSearch description document|OpenSearch description document]]. : Requirements: The element may appear zero or one time. ''Example:'' <startIndex>11</startIndex> ==== The "itemsPerPage" element ==== 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.'' : Restrictions: The value must a non-negative integer. : Default: The default value is equal to the number of search results on the current page. : Requirements: The element may appear zero or one time. ''Example:'' <itemsPerPage>10</itemsPerPage> ==== The "Query" element ==== Defines a search query that can be performed by search clients. Please see the [[#OpenSearch Query element|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.'' : Requirements: The element may appear zero or more times. ''Example:'' <Query role="request" searchTerms="cat" /> === Response metadata in HTML/XHTML === OpenSearch response metadata may be included in well-formed HTML/XHTML via the [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.2 HTML 4.0.1 "meta" element]. The following meta element "name" attribute values are recognized under the profile associated with the [[#Namespace|OpenSearch 1.1 namespace]]: : <code>"totalResults"</code> - Corresponds to value of the [[#The "totalResults" element|"totalResults" element]]. : <code>"startIndex"</code> - Corresponds to value of the [[#The "startIndex" element|"startIndex" element]]. : <code>"itemsPerPage"</code> - Corresponds to value of the [[#The "itemsPerPage" element|"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" "<nowiki>http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</nowiki>"> <html xmlns="<nowiki>http://www.w3.org/1999/xhtml</nowiki>" xml:lang="en" lang="en"> <head profile="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" > <title>Example.com Search: New York history</title> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>" title="Example.com Web Search" /> <meta name="totalResults" content="4230000"/> <meta name="startIndex" content"1"/> <meta name="itemsPerPage" content="10"/> </head> <nowiki><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></nowiki> </html> == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == 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> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] Specifications/OpenSearch/Changelog 1416 1445 2006-07-25T18:22:41Z DeWitt 2 == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the [[OpenSearch parameter extension]]. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Removed the <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. 1446 2006-07-25T18:23:13Z DeWitt 2 [[Specification/Changelog]] moved to [[Specifications/Changelog]] == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the [[OpenSearch parameter extension]]. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Removed the <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. 1451 2006-07-25T20:15:38Z DeWitt 2 [[Specifications/Changelog]] moved to [[Specifications/OpenSearch/Changelog]] == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the [[OpenSearch parameter extension]]. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Removed the <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. 1485 2006-08-08T16:20:32Z DeWitt 2 /* Version 1.1, Draft 3, Release Candidate */ == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the OpenSearch parameter extension. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Removed the <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. 1596 2006-08-09T17:51:52Z DeWitt 2 /* Version 1.1, Draft 3, Release Candidate */ == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the OpenSearch parameter extension. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Replaced the OpenSearch <code><link/></code> element with the standard Atom <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. 1719 2006-09-05T20:54:56Z DeWitt 2 Protected "[[Specifications/OpenSearch/Changelog]]" [edit=sysop:move=sysop] == Version 1.1, Draft 3, Release Candidate == * Merged core specification into single document. * Moved the <code><Param/></code> element and the <code><Url/></code> element's '<code>method</code>' attribute to the OpenSearch parameter extension. * Added the '<code>indexOffset</code>' and '<code>pageOffset</code>' to the <code><Url/></code> element. * Replaced the OpenSearch <code><link/></code> element with the standard Atom <code><link/></code> element. == Version 1.1, Draft 2 (December 6 2005) == * Unified XML namespace across core specifications. * Added section on autodiscovery. * Modified <code><Tags/></code> value to allow up to 256 characters. * Modified <code><Contact/></code> and <code><Tags/></code> elements to make them optional. * Modified <code><atom:link rel="..."/></code> values to match Atom specification. * Added <code><Query/></code> element. * Replaced <code><SampleSearch/></code> element in description with <code><Query role="example"/></code>. * Replaced <code><searchTerms/></code> element in response with <code><Query role="request"/></code>. == Version 1.1, Draft 1 (September 9 2005) == * Updated XML namespaces to reflect the new version. * Moved information regarding host restrictions to query syntax specification. * Modified <code><Image/></code> element to allow multiple occurrences. * Added '<code>width</code>', '<code>height</code>', and '<code>type</code>' attributes to <code><Image/></code> element. * Added <code><Language/></code>, <code><OutputEncoding/></code>, and <code><InputEncoding/></code> elements to description. * Added '<code>language</code>', '<code>outputEncoding</code>', and '<code>inputEncoding</code>' as core search parameters. * Specified MIME type for description documents. * Specified extensibility mechanism for custom search parameters. * Added '<code>?</code>' modifier for search parameters. * Specified extensibility mechanism for description documents. * Specified use of <code><atom:link/></code> elements in response. * Added <code><searchTerms/></code> element to response. * Added '<code>template</code>', '<code>type</code>', and '<code>method</code>' attributes to <code><Url/></code> element. * Added '<code><Param/></code> element to <code><Url/></code> element to support POST requests. * Modified <code><Url/></code> elements to allow multiple occurrences. * Removed <code><Format/>/code> element from description. * Renamed OpenSearch RSS to OpenSearch Response. * Added support for Atom, HTML, and other response formats. == Version 1.0 (March 15 2005) == * Released OpenSearch Description, OpenSearch Query Syntax, and OpenSearch RSS core specifications. Specifications/OpenSearch/Extensions 1433 1551 2006-08-09T15:33:51Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions|OpenSearch Suggestions extension]] 1569 2006-08-09T16:11:03Z DeWitt 2 /* Draft extension specifications */ == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] 1905 2007-06-06T16:13:43Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0|OpenSearch Geo extension]] 1906 2007-06-06T16:38:32Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] 1933 2007-08-11T18:42:25Z GregorRothfuss 23 added geo == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension]] 1939 2007-10-15T22:31:51Z DeWitt 2 /* Draft extension specifications */ == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] 2086 2008-09-29T21:37:19Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Refinement/1.0/|OpenSearch Refinement extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] 2099 2008-10-01T23:07:06Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] 2160 2008-11-19T18:55:55Z Screaminggeek 241 Adding links to extension proposals from the community proposal section of the wiki. == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.0|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] === Extension proposals from the Community === * [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] 2201 2009-01-30T06:52:53Z DeWitt 2 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] === Extension proposals from the Community === * [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] 2319 2009-11-30T10:50:18Z Tonyhammond 719 /* Extension proposals from the Community */ == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] === Extension proposals from the Community === * [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] 2374 2010-03-05T11:08:15Z Pduchesne 859 == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] === Extension proposals from the Community === * [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Semantic/1.0/Draft_1|OpenSearch Semantic extension (Draft)]] 2441 2010-09-10T14:30:07Z Pedro 922 /* Draft extension specifications */ == Draft extension specifications == * [[Specifications/OpenSearch/Extensions/Referrer/1.0|OpenSearch Referrer extension]] * [[Specifications/OpenSearch/Extensions/Relevance/1.0|OpenSearch Relevance extension]] * [[Specifications/OpenSearch/Extensions/Parameter/1.0|OpenSearch Parameter extension]] * [[Specifications/OpenSearch/Extensions/Suggestions/1.1|OpenSearch Suggestions extension]] * [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|OpenSearch Geo extension (Draft)]] * [[Specifications/OpenSearch/Extensions/Time/1.0/Draft_1|OpenSearch Time extension (Draft)]] === Extension proposals from the Community === * [[Community/Proposal/Specifications/OpenSearch/Extensions/Advertisement/1.0/Draft_1|OpenSearch Advertisement extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Commerce/1.0/Draft_1|OpenSearch Commerce extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Mobile/1.0/Draft_1|OpenSearch Mobile extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Spelling/1.0/Draft_1|OpenSearch Spelling extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/SRU/1.0/Draft_1|OpenSearch SRU extension (Draft)]] * [[Community/Proposal/Specifications/OpenSearch/Extensions/Semantic/1.0/Draft_1|OpenSearch Semantic extension (Draft)]] Specifications/OpenSearch/Extensions/Geo/1.0/Draft 1 1586 1907 2007-06-06T16:38:58Z DeWitt 2 New page: == Notice == {{Draft notice}} == Introduction == TODO === Geospatial Search === More search engines are providing support for geographic queries. Therefore, it is useful to provide a ... == Notice == {{Draft notice}} == Introduction == TODO === Geospatial Search === More search engines are providing support for geographic queries. Therefore, it is useful to provide a common, OpenSearch standard, for querying geospatial data. The geospatial parameters are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. How to resolve the discrepancy between KML & GeoRSS with respect to lat/lon order? It would be nice to 'support' both formats easily. Network links to Opensearch for example, but results in RSS will be the reverse order. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact>robot@mapufacture.com</Contact> <Image width="16" height="16" type="image/x-icon">http://mapufacture.com/favicon.ico</Image> <Url type="text/html" template="http://mapufacture.com/search?keyword={searchTerms}"/> <Url type="application/rss+xml" xmlns:georss="http://georss.org/1" template="http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geo-spacial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "point" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&p={point?}&r={radius?}&format=rss Replaced with the "latitude, longitude", in decimal degrees in EPSG:4326 (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&p=43.25,-83.45&format=rss === The "radius" parameters === === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&within={box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in EPSG:4326 decimal degrees. Example: http://example.com/?q=pizza&within=42.943,-71.032,43.039,-69.856&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&area={polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined clockwise <note name="andrew">boo! bbox is ccw, polygon is cw</note> with the last point being the same as the first in order to close the polygon. Example: http://example.com/?q=pizza&area=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1908 2007-06-12T15:09:44Z AndrewTurner 66 Added link to EPSG definition - added geo: namespace to parameters == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact>robot@mapufacture.com</Contact> <Image width="16" height="16" type="image/x-icon">http://mapufacture.com/favicon.ico</Image> <Url type="text/html" template="http://mapufacture.com/search?keyword={searchTerms}"/> <Url type="application/rss+xml" xmlns:georss="http://georss.org/1" template="http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in <a href="http://nsidc.org/data/atlas/epsg_4326.html" title="National Snow and Ice Center: EPSG 4326 definition">EPSG:4326</a> (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&p=43.25,-83.45&format=rss === The "radius" parameters === === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&within={geo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in <a href="http://nsidc.org/data/atlas/epsg_4326.html" title="National Snow and Ice Center: EPSG 4326 definition">EPSG:4326</a> decimal degrees. Example: http://example.com/?q=pizza&within=42.943,-71.032,43.039,-69.856&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&area={geo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined clockwise <note name="andrew">boo! bbox is ccw, polygon is cw</note> with the last point being the same as the first in order to close the polygon. Example: http://example.com/?q=pizza&area=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1909 2007-06-12T15:11:04Z AndrewTurner 66 /* The "polygon" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact>robot@mapufacture.com</Contact> <Image width="16" height="16" type="image/x-icon">http://mapufacture.com/favicon.ico</Image> <Url type="text/html" template="http://mapufacture.com/search?keyword={searchTerms}"/> <Url type="application/rss+xml" xmlns:georss="http://georss.org/1" template="http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in <a href="http://nsidc.org/data/atlas/epsg_4326.html" title="National Snow and Ice Center: EPSG 4326 definition">EPSG:4326</a> (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&p=43.25,-83.45&format=rss === The "radius" parameters === === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&within={geo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in <a href="http://nsidc.org/data/atlas/epsg_4326.html" title="National Snow and Ice Center: EPSG 4326 definition">EPSG:4326</a> decimal degrees. Example: http://example.com/?q=pizza&within=42.943,-71.032,43.039,-69.856&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&area={geo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined clockwise with the last point being the same as the first in order to close the polygon. Example: http://example.com/?q=pizza&area=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1910 2007-06-12T15:11:48Z AndrewTurner 66 /* The "box" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact>robot@mapufacture.com</Contact> <Image width="16" height="16" type="image/x-icon">http://mapufacture.com/favicon.ico</Image> <Url type="text/html" template="http://mapufacture.com/search?keyword={searchTerms}"/> <Url type="application/rss+xml" xmlns:georss="http://georss.org/1" template="http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in <a href="http://nsidc.org/data/atlas/epsg_4326.html" title="National Snow and Ice Center: EPSG 4326 definition">EPSG:4326</a> (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&p=43.25,-83.45&format=rss === The "radius" parameters === === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&within={geo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. Example: http://example.com/?q=pizza&within=42.943,-71.032,43.039,-69.856&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&area={geo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined clockwise with the last point being the same as the first in order to close the polygon. Example: http://example.com/?q=pizza&area=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1911 2007-06-12T15:18:54Z AndrewTurner 66 Added optional parameters example == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact>robot@mapufacture.com</Contact> <Image width="16" height="16" type="image/x-icon">http://mapufacture.com/favicon.ico</Image> <Url type="text/html" template="http://mapufacture.com/search?keyword={searchTerms}"/> <Url type="application/rss+xml" xmlns:georss="http://georss.org/1" template="http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&lat=43.25&lon=-83.45&format=rss === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: http://example.com/?q=pizza&lat=43.25&lon=-83.45&radius=10000&format=rss === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&within={geo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. Example: http://example.com/?q=pizza&within=42.943,-71.032,43.039,-69.856&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&area={geo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined clockwise with the last point being the same as the first in order to close the polygon. Example: http://example.com/?q=pizza&area=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: http://example.com/?q={searchTerms}&pw={startPage?}&area={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1912 2007-06-12T16:25:22Z AndrewTurner 66 Added Atom and KML Responses - changed namespace to opensearchgeo to reflect its specific use == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact><nowiki>robot@mapufacture.com</nowiki></Contact> <Image width="16" height="16" type="image/x-icon"><nowiki>http://mapufacture.com/favicon.ico</nowiki></Image> <Url type="text/html" template="<nowiki>http://mapufacture.com/search?keyword={searchTerms}</nowiki>"/> <Url type="application/rss+xml" xmlns:georss="<nowiki>http://georss.org/1</nowiki>" template="<nowiki>http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}</nowiki>"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response == Request: http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722" Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.NYC - A virtual tour and information on businesses ... with historic photos of Union Square's own New York neighborhood ... Internet Resources for the City's History. ... </content> </entry> </feed> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <LineString> <coordinates>-73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0</coordinates> </LineString> </Placemark> </Document> </kml> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1913 2007-06-12T16:28:07Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact><nowiki>robot@mapufacture.com</nowiki></Contact> <Image width="16" height="16" type="image/x-icon"><nowiki>http://mapufacture.com/favicon.ico</nowiki></Image> <Url type="text/html" template="<nowiki>http://mapufacture.com/search?keyword={searchTerms}</nowiki>"/> <Url type="application/rss+xml" xmlns:georss="<nowiki>http://georss.org/1</nowiki>" template="<nowiki>http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}</nowiki>"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: http://example.com/?q=pizza&l=boston&format=rss === The "lat" and "lon" parameters === http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss === The "box" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss === The "polygon" parameter === http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response == Request: http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722" Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.NYC - A virtual tour and information on businesses ... with historic photos of Union Square's own New York neighborhood ... Internet Resources for the City's History. ... </content> </entry> </feed> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722" <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <LineString> <coordinates>-73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0</coordinates> </LineString> </Placemark> </Document> </kml> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1914 2007-06-12T16:31:13Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact><nowiki>robot@mapufacture.com</nowiki></Contact> <Image width="16" height="16" type="image/x-icon"><nowiki>http://mapufacture.com/favicon.ico</nowiki></Image> <Url type="text/html" template="<nowiki>http://mapufacture.com/search?keyword={searchTerms}</nowiki>"/> <Url type="application/rss+xml" xmlns:georss="<nowiki>http://georss.org/1</nowiki>" template="<nowiki>http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}</nowiki>"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response == Request: <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.NYC - A virtual tour and information on businesses ... with historic photos of Union Square's own New York neighborhood ... Internet Resources for the City's History. ... </content> </entry> </feed> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <LineString> <coordinates>-73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0</coordinates> </LineString> </Placemark> </Document> </kml> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1915 2007-06-12T16:38:13Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. One way is to just use the georss namespace (or kml) which would be valid even right now: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <ShortName>Mapufacture</ShortName> <Description>Search for geographic items in Mapufacture</Description> <Tags>geo georss location kml</Tags> <Contact><nowiki>robot@mapufacture.com</nowiki></Contact> <Image width="16" height="16" type="image/x-icon"><nowiki>http://mapufacture.com/favicon.ico</nowiki></Image> <Url type="text/html" template="<nowiki>http://mapufacture.com/search?keyword={searchTerms}</nowiki>"/> <Url type="application/rss+xml" xmlns:georss="<nowiki>http://georss.org/1</nowiki>" template="<nowiki>http://mapufacture.com/search.rss?keyword={searchTerms}&bbox={georss:bbox?}</nowiki>"/> </OpenSearchDescription> == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> . == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1916 2007-06-15T16:50:25Z AndrewTurner 66 Removed georss namespace example == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> . == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1917 2007-06-15T17:50:12Z GregorRothfuss 23 /* KML Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver), comma-separated. This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> . == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1918 2007-06-15T19:59:18Z AndrewTurner 66 /* The "lat" and "lon" parameters */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> . == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1920 2007-06-15T20:01:37Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1924 2007-07-14T00:38:34Z DeWitt 2 /* KML Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki></code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1925 2007-07-14T00:39:22Z DeWitt 2 /* The "locationString" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki> </code> Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example: <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> === The "lat" and "lon" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki></code> Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki></code> Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example: <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> === The "polygon" parameter === : <code>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</code> Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example: <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1926 2007-07-14T00:42:40Z DeWitt 2 /* Parameters */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Request: : <code><nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki></code> Response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1927 2007-07-14T00:48:13Z DeWitt 2 /* Atom Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1928 2007-07-14T00:49:56Z DeWitt 2 /* KML Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={opensearchgeo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={opensearchgeo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&r={opensearchgeo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. opensearchgeo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={opensearchgeo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={opensearchgeo:polygon?}&lat={opensearchgeo:lat?}&lon={opensearchgeo:lon?}&d={opensearchgeo:radius?}&bbox={opensearchgeo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" opensearchgeo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1931 2007-07-27T16:42:08Z AndrewTurner 66 Changed namespace from opensearchgeo to just geo. == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1932 2007-08-07T20:09:34Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1938 2007-10-14T16:08:01Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2242 2009-08-07T18:51:35Z AndrewTurner 66 /* The "box" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2443 2010-09-23T08:29:34Z Pedro 922 /* Notice */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2589 2011-09-13T10:24:59Z Pedro 922 /* The "locationString" parameter */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2590 2011-09-13T10:25:34Z Pedro 922 /* The "polygon" parameter */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2591 2011-09-13T10:42:21Z Pedro 922 /* The "locationString" parameter */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2592 2011-09-13T10:42:45Z Pedro 922 /* The "polygon" parameter */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2593 2011-09-13T10:44:26Z Pedro 922 /* Introduction */ == Notice == {{Draft notice}} A new version of this document is available [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]] == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. '''Update''' : New draft available (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&bbox=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). '''Warning''' : This element was changed on Draft 2 (see [[Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2|here]]) Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Geo/1.0/Draft 2 1723 2227 2009-04-17T14:13:46Z DeWitt 2 New page: == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use.... == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "locationString" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:locationString?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2400 2010-05-06T05:52:44Z JoWalsh 906 made trivial changes now need to refer to the draft, samples etc == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2401 2010-05-06T10:36:45Z Oscar.fonts 905 /* Atom Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2402 2010-05-06T10:38:36Z Oscar.fonts 905 /* KML Response */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2405 2010-05-14T15:27:03Z Oscar.fonts 905 /* The "name" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "polygon" parameter === Replaced with the latitude/longitude pairs describing a bounding area to perform a search within. The polygon is defined in latitude, longitude pairs, in clockwise order around the polygon, with the last point being the same as the first in order to close the polygon. Note: it is important to specify that the polygon is defined in clockwise order. Otherwise in some cases the search criteria would not be clear. For example, searching the polygon: -80, -170, 0, -170, 80, -170, 80, 170, 0, 170, -80, 170, -80, -170; it would not be clear if this was a nearly-global search or just a search along the date-time line (or anti-meridian). Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&p=45.256,-110.45,46.46,-109.48,43.84,-109.86,45.256,-110.45&format=rss</nowiki> </code> == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2406 2010-05-14T16:07:35Z Oscar.fonts 905 /* The "polygon" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON * GEOMETRYCOLLECTION Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(4 6,7 10)) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2407 2010-05-14T16:08:20Z Oscar.fonts 905 /* Contributors */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON * GEOMETRYCOLLECTION Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(4 6,7 10)) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Jo Walsh Oscar Fonts == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2408 2010-05-14T16:08:48Z Oscar.fonts 905 /* Contributors */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON * GEOMETRYCOLLECTION Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(4 6,7 10)) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Jo Walsh Oscar Fonts == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2414 2010-05-21T14:07:35Z JoWalsh 906 /* Contributors */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON * GEOMETRYCOLLECTION Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(4 6,7 10)) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Andrew Turner Jo Walsh Oscar Fonts Pedro Goncalves == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2442 2010-09-15T21:49:41Z Oscar.fonts 905 /* The "geometry" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Andrew Turner Jo Walsh Oscar Fonts Pedro Goncalves == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2447 2010-11-17T09:00:48Z Pedro 922 /* Introduction */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standard. Therefore, latitude/longitude order, bounding box parameters are using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Andrew Turner Jo Walsh Oscar Fonts Pedro Goncalves == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43589 2013-08-14T17:08:00Z Pedro 922 /* The "geometry" parameter */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standard. Therefore, latitude/longitude order, bounding box parameters are using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Geo extension namespace was shortened to just "geo" instead of "opensearchgeo". This was to make the namespace more succinct. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:geo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <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/vnd.google-earth.kml+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=kml</nowiki>"/> <Url type="application/atom+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=atom</nowiki>"/> <Url type="application/rss+xml" template="<nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&bbox={geo:box?}&pw={startPage?}</nowiki>"/> <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"><nowiki>http://example.com/websearch.ico</nowiki></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> == Namespace == The XML namespace of the OpenSearch Geo Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "name" parameter === Replaced with a string describing the location (place name) to perform the search. This location string will be parsed and geocoded by the search service. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&l={geo:name?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&l=boston&format=rss</nowiki> </code> ==== The "locationString" parameter (deprecated) ==== Use the "name" parameter instead. === The "lat" and "lon" parameters === Replaced with the "latitude, longitude", respectively, in decimal degrees in [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] (typical WGS84 coordinates as returned by a GPS receiver). This parameter should also include a "radius" parameter that specifies the search radius, in meters. If no radius is supplied, then the search service is free to use a default radius but should specify this radius in the returned result. Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&lat={geo:lat?}&lon={geo:lon?}&r={geo:radius?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&format=rss</nowiki> </code> === The "radius" parameters === The radius parameter, used with the lat and lon parameters, specifies the search distance from this point. The distance is in meters along the Earth's surface. Example: <nowiki>http://example.com/?q=pizza&lat=43.25&lon=-123.45&radius=10000&format=rss</nowiki> === The "box" parameter === Replaced with the bounding box to search for geospatial results within. The box is defined by "west, south, east, north" coordinates of longitude, latitude, in a [http://nsidc.org/data/atlas/epsg_4326.html EPSG:4326] decimal degrees. This is also commonly referred to by minX, minY, maxX, maxY (where longitude is the X-axis, and latitude is the Y-axis), or also SouthWest corner and NorthEast corner. geo:box ~ west, south, east, north Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&bbox={geo:box?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&b=-111.032,42.943,-119.856,43.039&format=rss</nowiki> </code> === The "geometry" parameter === Replaced with a geometry defined using the Well Known Text (WKT) standard. The following 2D geometric objects can be described: * POINT * LINESTRING * POLYGON * MULTIPOINT * MULTILINESTRING * MULTIPOLYGON Note that the WKT coordinate pairs are in lon, lat order; opposit to GeoRSS. Polygons are a collection of linearrings. The outer ring is expressed in counter-clockwise order. Internal rings have the opposite orientation, appearing as clockwise (see 6.1.11.1 in OGC Simple Features Specification v. 1.2.0). Spaces must be URL encoded ('%20' or '+') in the request. Example geometries: <code> POINT(6 10) LINESTRING(3 4,10 50,20 25) POLYGON((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)) MULTIPOINT(3.5 5.6, 4.8 10.5) MULTILINESTRING((3 4,10 50,20 25),(-5 -8,-10 -8,-15 -4)) MULTIPOLYGON(((1 1,5 1,5 5,1 5,1 1),(2 2,2 3,3 3,3 2,2 2)),((6 3,9 2,9 4,6 3))) </code> Example URL template: <code> <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&g={geo:geometry?}&format=rss</nowiki> </code> Example request: <code> <nowiki>http://example.com/?q=pizza&g=POLYGON((0.582%2040.496%2C%200.231%2040.737%2C%200.736%2042.869%2C%203.351%2042.386%2C%203.263%2041.814%2C%202.164%2041.265%2C%200.978%20%20%2040.957%2C%200.802%2040.781%2C%200.978%2040.649%2C%200.582%2040.496))&format=rss</nowiki> </code> References: * Wikipedia: http://en.wikipedia.org/wiki/Well-known_text#Geometric_objects * OGC Simple Features Specification: http://portal.opengeospatial.org/files/?artifact_id=18241 ==== The "polygon" parameter (deprecated) ==== Use the "geometry" parameter instead. === The "relation" parameter === Replace by the spatial relation of the search. By default the geo searches return the records that intersect the query. The possible values are: * intersects (default) * contains * disjoint === The "uid" parameter === Replace by the identifier of the resource within the search engine context (local reference). This parameter is used to query resources by their fragment identifier, unique within the search scope only. It can be used to query local identifiers that are not URI including the support of GML identifiers == Optional Parameters == The search server should use the "?" flag in the URL template when requesting the source parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. Therefore, if a service provides multiple optional geographic search parameters, these can be combined into a single definition of optional parameters: Example: <nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&p={geo:polygon?}&lat={geo:lat?}&lon={geo:lon?}&d={geo:radius?}&bbox={geo:box?}&format=kml</nowiki> == Geo response elements == The OpenSearch-Geo response elements can be used by search engines to augment existing XML formats with search-related metadata. See the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch response] definition for a general overview of the response options. The following examples illustrate Geo-specific responses. For RSS and Atom responses, it is suggested to use the GeoRSS channel elements in addition to the OpenSearch-Geo elements. === Atom Response === Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=atom&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:georss="<nowiki>http://www.georss.org/georss</nowiki>"> <title>Example.com Search: New York history</title> <link href="<nowiki>http://example.com/New+York+history</nowiki>"/> <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="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722" type="text/html"/> <link rel="search" type="application/opensearchdescription+xml" href="<nowiki>http://example.com/opensearchdescription.xml</nowiki>"/> <georss:box>40.69418 -74.0667 40.7722 -73.9116</georss:box> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <georss:line>40.73763 -73.9972 40.73519 -73.99167 40.737015 -73.99035 40.73643 -73.98914 40.734640 -73.990431 40.731617 -73.991504</georss:line> <content type="text"> ... Union Square.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> === KML Response === KML is an acceptable and recommended response option for geospatial searches. KML allows for styling and complex responses, similar to HTML response for non-spatial queries. Example request: <code> <nowiki>http://example.com/New+York+History?pw=3&format=kml&bbox=-74.0667,40.69418,-73.9116,40.7722"</nowiki> </code> Example response: <code> <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="<nowiki>http://earth.google.com/kml/2.2</nowiki>" xmlns:atom="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchgeo="<nowiki>http://a9.com/-/opensearch/extensions/geo/1.0/</nowiki>"> <opensearch:totalResults>4230000</opensearch:totalResults> <opensearch:startIndex>21</opensearch:startIndex> <opensearch:itemsPerPage>10</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="New York History" startPage="3" geo:box="-74.0667,40.69418,-73.9116,40.7722"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722</nowiki>" type="text/html"/> <atom:link rel="alternate" href="<nowiki>http://example.com/New+York+History?pw=3&bbox=-74.0667,40.69418,-73.9116,40.7722&format=atom</nowiki>" type="application/atom+xml"/> <Document> <name>NYCHistory.kml</name> <open>1</open> <Placemark> <name>New York History</name> <atom:link><nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki></atom:link> <LineString> <coordinates> -73.9972,40.73763,0 -73.99167,40.73519,0 -73.99035,40.737015,0 -73.98914,40.73643,0 -73.990431,40.734640,0 -73.991504,40.731617,0 </coordinates> </LineString> </Placemark> </Document> </kml> </code> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> Andrew Turner Jo Walsh Oscar Fonts Pedro Goncalves == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Parameter 1437 1562 2006-08-09T16:08:26Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Parameter]] moved to [[Specifications/OpenSearch/Extensions/Parameter/1.0]] #REDIRECT [[Specifications/OpenSearch/Extensions/Parameter/1.0]] 2042 2008-06-15T18:12:44Z Xyzzy 262 Fix [[Special:DoubleRedirects]] #REDIRECT [[Specifications/OpenSearch/Extensions/Parameter/1.0/Draft_1]] Specifications/OpenSearch/Extensions/Parameter/1.0 1454 1631 2006-08-11T11:59:29Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Parameter/1.0]] moved to [[Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 1]] #REDIRECT [[Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 1]] Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 1 1436 1559 2006-08-09T16:07:32Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> 1560 2006-08-09T16:07:53Z DeWitt 2 /* Author */ == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1561 2006-08-09T16:08:26Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Parameter]] moved to [[Specifications/OpenSearch/Extensions/Parameter/1.0]] == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1576 2006-08-09T16:27:52Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1630 2006-08-11T11:59:29Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Parameter/1.0]] moved to [[Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 1]] == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1716 2006-09-05T20:54:12Z DeWitt 2 Protected "[[Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 1]]" [edit=sysop:move=sysop] == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Parameter/1.0/Draft 2 36508 43583 2013-06-17T18:34:17Z DeWitt 2 New page: == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSea... == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximim number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43584 2013-06-18T16:13:24Z Pedro 922 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>min</code> - Contains a string that identifies minimal value for the element in a string comparison operator. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>max</code> - Contains a string that identifies maximal value for the element in a string comparison operator. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="http://example.com/opensearchextensions/1.0/" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43585 2013-06-18T18:50:36Z Pedro 922 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>minExclusive</code> - Contains a string that identifies the minimum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxExclusive</code> - Contains a string that identifies maximum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>minInclusive</code> - Contains a string that identifies minimum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxInclusive</code> - Contains a string that identifies maximum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="http://example.com/opensearchextensions/1.0/" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43586 2013-06-18T19:02:03Z Pedro 922 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>minExclusive</code> - Contains a string that identifies the minimum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxExclusive</code> - Contains a string that identifies maximum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>minInclusive</code> - Contains a string that identifies minimum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxInclusive</code> - Contains a string that identifies maximum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> ''Example of a Parameter element used to represent an optional time extension custom search parameter restricted to 2011'' <Parameter xmlns:custom="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z" pattern="[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[\+\-][0-9]{2}:[0-9]{2})" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43587 2013-06-18T19:33:49Z Pedro 922 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>minExclusive</code> - Contains a string that identifies the minimum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxExclusive</code> - Contains a string that identifies maximum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>minInclusive</code> - Contains a string that identifies minimum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxInclusive</code> - Contains a string that identifies maximum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> ''Example of a Parameter element used to represent an optional time extension custom search parameter restricted to 2011'' <Parameter xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z" pattern="[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[\+\-][0-9]{2}:[0-9]{2})" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43588 2013-06-18T20:54:39Z Pedro 922 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>minExclusive</code> - Contains a string that identifies the minimum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxExclusive</code> - Contains a string that identifies maximum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>minInclusive</code> - Contains a string that identifies minimum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxInclusive</code> - Contains a string that identifies maximum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> ''Example of a Parameter element used to represent an optional time extension custom search parameter restricted to 2011'' <Parameter xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z" pattern="[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[\+\-][0-9]{2}:[0-9]{2})" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> '' Example of a OpenSearch Description supporting the Earth Observation and Temporal Extensions. The OpenSearch Parameter extension elements are used to suggest clients the possible values for temporal range and acquisition station names'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:eo="<nowiki>http://a9.com/-/opensearch/extensions/eo/1.0/</nowiki>" xmlns:param="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" > <ShortName>Web Search</ShortName> <LongName>Example.com Web Search</LongName> <Description>Use Example.com to search the Web.</Description> <Tags>example web</Tags> <Contact>admin@example.com</Contact> <Url type="application/atom+xml" template="<nowiki>http://example.com/myatom/?pw={startPage?}&acq={eo:acquisitionStation?}&</nowiki> start={time:start?}& end={time:end?}"/> <param:Parameter name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z"/> <param:Parameter name="end" value="{time:end}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z"/> <param:Parameter name=”acq” value=”eo:acquisitionStation” minimum=”0” title=”Acquisiton Station”> <param:Option value="PDHS-K" label=”Kiruna”/> <param:Option value="PDHS-E" label=”ESRIN”/ > </param:Parameter> <Attribution>Copyright 2005, Example.com, Inc.</Attribution> <SyndicationRight>open</SyndicationRight> </OpenSearchDescription> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 43591 2013-10-30T04:47:09Z DeWitt 2 == Notice == {{Template:Draft notice}} == Overview == The OpenSearch parameter extension is an enhancement to the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]] that enables an augmented query parameter suggestion and validation mechanism via structured XML. The extension also includes a mechanism for specifying alternate HTTP request methods, such as POST, and a mechanism for specifying alternate request encodings, such as " multipart/form-data". ''Example of a Url element that uses the OpenSearch parameter extension to specify a POST search interface:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="text/html" template="h<nowiki>ttp://example.com/search</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded"> <parameters:Parameter name="q" value="{searchTerms}"/> <parameters:Parameter name="count" value="{itemsPerPage}" minimum="0"/> <parameters:Parameter name="start" value="{startIndex}" minimum="0"/> </Url> == Namespace == The XML Namespaces URI for the OpenSearch parameter extension is: : <nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki> == Elements == === The "Url" element === The OpenSearch parameter extension adds two new attributes to the [[Specifications/OpenSearch/1.1#The "Url" element|"Url" element]] in the [[Specifications/OpenSearch/1.1#OpenSearch description document|OpenSearch description document]]. ''The new attributes must be explicitly associated with the [[#Namespace|OpenSearch parameter extension namespace]] via a valid XML prefix.'' : New Attributes: :: <code>method</code> - Contains a case-insensitive string that identifies the HTTP request method that the search client should use to perform the search request. ::: Restrictions: Must be a valid [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 HTTP request method], as specified in RFC 2616. ::: Default: "get" ::: Requirements: This attribute is optional. :: <code>enctype</code> - Contains a string that identifies the content encoding the search client should use to perform the search request. ::: Default: "application/x-www-form-urlencoded" ::: Requirements: This attribute is optional. ''Example of a Url element that specifies a HTTP POST query:'' <Url xmlns:parameters="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" type="application/atom+xml" template="<nowiki>http://example.com/search?q={searchTerms}</nowiki>" parameters:method="POST" parameters:enctype="application/x-www-form-urlencoded" /> === The "Parameter" element === Describes a name/value pair to be included in the search request. : Parent: Url : Attributes: :: <code>name</code> - Contains the name of the parameter. ::: Restrictions: Must be a valid parameter name for format identified by the "enctype" parameter on the containing "Url" element. ::: Requirements: This attribute is '''required'''. :: <code>value</code> - Contains a string that will be processed according to the rules of the [[Specifications/OpenSearch/1.1#OpenSearch URL template syntax|OpenSearch URL template syntax]]. ::: Default: "" ::: Requirements: This attribute is optional. :: <code>minimum</code> - Contains a string that identifies the minimum number of times this parameter must be included in the search request. ::: Restrictions: The value must be a non-negative integer. ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>maximum</code> - Contains a string that identifies the maximum number of times this parameter must be included in the search request. The literal string "*" will be interpreted to mean that the parameter may repeat an arbitrary number of times. ::: Restrictions: The value must be a non-negative integer or the literal string "*". ::: Default: "1" ::: Requirements: This attribute is optional. :: <code>pattern</code> - Contains a string that specifies a regular expression against which the parameter's value. When present the element should also include a title attribute to inform the client application of the format expected. ::: Restrictions: Must be a valid pattern according to the [http://www.ecma-international.org/publications/standards/Ecma-262.htm JavaScript] Pattern production. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>title</code> - Contains a string with advisory information for the format and valid values of the parameter, such as would be appropriate for a tooltip. ::: Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Default: "" ::: Requirements: This attribute is optional but recommended when a pattern attribute is present. :: <code>minExclusive</code> - Contains a string that identifies the minimum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxExclusive</code> - Contains a string that identifies maximum value for the element that cannot be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>minInclusive</code> - Contains a string that identifies minimum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>maxInclusive</code> - Contains a string that identifies maximum value for the element that can be reached. Applies only to numeric and date types. ::: Default: "" ::: Requirements: This element may appear zero or one time. :: <code>step</code> - Contains a string that identifies the granularity of the allowed values between the minimal and maximal range. ::: Default: "" ::: Requirements: This element may appear zero or one time (only relevant when the max or min attributes are present). ''Example of a Parameter element used to represent a simple required core search parameter:'' <Parameter name="q" value="{searchTerms}" /> ''Example of a Parameter element used to represent a simple optional core search parameter:'' <Parameter name="start" value="{startIndex}" minimum="0" /> ''Example of a Parameter element used to represent a repeating custom search parameter:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="tag" value="{custom:tag}" minimum="0" maximum="*" /> ''Example of a Parameter element used to represent an optional time extension custom search parameter restricted to 2011'' <Parameter xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z" pattern="[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[\+\-][0-9]{2}:[0-9]{2})" /> === The "Option" element === Describes a value/label pair suggested to the client for the parent element. : Parent: Parameter : Attributes: :: <code>value</code> - Contains a string with the value of the option. ::: Restrictions: The value must be URL-encoded. ::: Requirements: This attribute is '''required'''. :: <code>label</code> - Contains a string that provides a label for the option. ::: Default: The value must contain 512 or fewer characters of plain text. The value must not contain HTML or other markup. ::: Requirements: This element may appear zero or one time. ''Example of a Parameter element used to represent a optional hexadecimal RGB color custom search parameter, with 3 suggested values:'' <Parameter xmlns:custom="<nowiki>http://example.com/opensearchextensions/1.0/</nowiki>" name="color" value="{custom:rgbcolor}" pattern="#(?:[0-9a-fA-F]{3}){1,2}" title="Color using a hex notation for the Red, Green, and Blue color values (RGB)" minimum="0" > <Option value="#0000FF" label="Blue"/> <Option value="#f00" label="Red"/> <Option value="#0F0" label="Green"/> </Parameter> '' Example of a OpenSearch Description supporting the Earth Observation and Temporal Extensions. The OpenSearch Parameter extension elements are used to suggest clients the possible values for temporal range and acquisition station names'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:eo="<nowiki>http://a9.com/-/opensearch/extensions/eo/1.0/</nowiki>" xmlns:param="<nowiki>http://a9.com/-/spec/opensearch/extensions/parameters/1.0/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>" > <ShortName>Web Search</ShortName> <LongName>Example.com Web Search</LongName> <Description>Use Example.com to search the Web.</Description> <Tags>example web</Tags> <Contact>admin@example.com</Contact> <Url type="application/atom+xml" template="<nowiki>http://example.com/myatom/?pw={startPage?}&acq={eo:acquisitionStation?}&</nowiki> start={time:start?}& end={time:end?}"> <param:Parameter name="start" value="{time:start}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z"/> <param:Parameter name="end" value="{time:end}" minimum="0" minInclusive="2011-01-01T00:00:00Z" maxExclusive="2012-01-01T00:00:00Z"/> <param:Parameter name=”acq” value=”eo:acquisitionStation” minimum=”0” title=”Acquisiton Station”> <param:Option value="PDHS-K" label=”Kiruna”/> <param:Option value="PDHS-E" label=”ESRIN”/ > </param:Parameter> </Url> <Attribution>Copyright 2005, Example.com, Inc.</Attribution> <SyndicationRight>open</SyndicationRight> </OpenSearchDescription> == Processing Rules == ''In general, the search client should follow the mechanisms for formulating the HTTP request according the encoding type specified via the "enctype" parameter. The OpenSeach parameter extension is intended to be open-ended and flexible and allow for future encoding types to be included as they are developed.'' ==== The "application/x-www-form-urlencoded" encoding type ==== The search request will constructed as type application/x-www-form-urlencoded, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1 Section 17.13.4.1 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. ==== The "multipart/form-data" encoding type ==== The search request will constructed as type multipart/form-data, as specified in [http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 Section 17.13.4.2 Form content types] of the [http://www.w3.org/TR/html401/ XHTML 4.0.1 specification]. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Pedro Gonçalves <pedro.goncalves@terradue.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Referrer 1438 1565 2006-08-09T16:09:30Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Referrer]] moved to [[Specifications/OpenSearch/Extensions/Referrer/1.0]] #REDIRECT [[Specifications/OpenSearch/Extensions/Referrer/1.0]] 2043 2008-06-15T18:14:08Z Xyzzy 262 Fix [[http://www.opensearch.org/Special:DoubleRedirects]] #REDIRECT [[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft_1]] 2044 2008-06-15T18:15:06Z Xyzzy 262 Reverted edits by [[Special:Contributions/Xyzzy|Xyzzy]] ([[User talk:Xyzzy|Talk]]); changed back to last version by [[User:DeWitt|DeWitt]] #REDIRECT [[Specifications/OpenSearch/Extensions/Referrer/1.0]] 2045 2008-06-15T18:17:12Z Xyzzy 262 EAGAIN, fix [[Special:DoubleRedirects]] with proper edit history #REDIRECT [[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft_1]] Specifications/OpenSearch/Extensions/Referrer/1.0 1458 1649 2006-08-17T18:37:02Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Referrer/1.0]] moved to [[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft 1]] #REDIRECT [[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft 1]] Specifications/OpenSearch/Extensions/Referrer/1.0/Draft 1 1435 1556 2006-08-09T16:00:35Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> 1557 2006-08-09T16:03:15Z DeWitt 2 /* Namespace */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> 1558 2006-08-09T16:03:26Z DeWitt 2 /* Example URL Template */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> 1563 2006-08-09T16:09:02Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1564 2006-08-09T16:09:30Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Referrer]] moved to [[Specifications/OpenSearch/Extensions/Referrer/1.0]] == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1571 2006-08-09T16:24:20Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1648 2006-08-17T18:37:01Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Referrer/1.0]] moved to [[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft 1]] == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1708 2006-09-05T17:17:10Z DeWitt 2 /* Author */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Michael Fagan <mifa@a9.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1715 2006-09-05T20:54:04Z DeWitt 2 Protected "[[Specifications/OpenSearch/Extensions/Referrer/1.0/Draft 1]]" [edit=sysop:move=sysop] == Notice == {{Draft notice}} == Introduction == The OpenSearch Referrer extension allows search engines to request a query parameter from search clients to indicate the source of the search. This parameter could be used to identify the particular search client, the version of the search client, additional information about the source of the search, or similar. == Namespace == The XML namespace of the OpenSearch Referrer Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == The OpenSearch Referrer Extension introduces the following parameter to be used in OpenSearch URL templates. === The "source" parameter === Replaced with a string identifying the search client that performed the search request. == Example URL Template == ''Example: An OpenSearch URL template with an optional source parameter:'' <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:referrer="<nowiki>http://a9.com/-/opensearch/extensions/referrer/1.0/</nowiki>"'''> <Url type="application/atom+xml" template="<nowiki>http://example.com/{searchTerms}</nowiki>?'''src={referrer:source?}'''"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Source Values == Values for the <code>source</code> parameter are not dictated by this specification. Search clients should make known and publish the list of values that they indend to send as a source parameter. For example, Internet Explorer 7 could send one of the following values, depending on where in the browser a search originated: : "IE-SearchBox" Or, : "IE-Address" The A9.com website could send the following value: : "a9.com" The Firefox web browser could send the following value: : "firefox-a" ''Note: Those values are used as examples only. Please refer to the documentation for the particular search client to determine the actual "source" values. == Optional Parameters == The search server should use the "<code>?</code>" flag in the URL template when requesting the <code>source</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension. == Author == DeWitt Clinton <dewitt@opensearch.org> == Contributors == Michael Fagan <mifa@a9.com> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Relevance/1.0 1455 1635 2006-08-11T16:26:10Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Relevance/1.0]] moved to [[Specifications/OpenSearch/Extensions/Relevance/1.0/Draft 1]] #REDIRECT [[Specifications/OpenSearch/Extensions/Relevance/1.0/Draft 1]] Specifications/OpenSearch/Extensions/Relevance/1.0/Draft 1 1440 1570 2006-08-09T16:22:16Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Relevance Extension allows search engines indicate a relative score in a particular domain for an individual search result. ''Example of a search result that includes a relevance score:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:relevance="<nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <relevance:score>0.95</relevance:score> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Relevance Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki> </code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Relevance extension introduces the following element. === The "score" element === Contains a string indicating a relative assessment of relevance for a particular search result with respect to the search query. Decimal values less than 0 should be considered equal to 0. Decimal values greater than 1 should be considered equal to 1. Unparseable or empty values can be ignored by the client. : Restrictions: The value must contain a decimal representation of a real number between 0 and 1, inclusive. : Requirements: This element may appear zero or one time. The <code>score</code> element is used to indicate a relative assessment of relevance for a particular search result with respect to the search query. ''Examples of <code>score</code> elements:'' <relevance:score>0.3</relevance:score> <relevance:score>0.924</relevance:score> <relevance:score>0.12</relevance:score> == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1575 2006-08-09T16:27:33Z DeWitt 2 /* License */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Relevance Extension allows search engines indicate a relative score in a particular domain for an individual search result. ''Example of a search result that includes a relevance score:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:relevance="<nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <relevance:score>0.95</relevance:score> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Relevance Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki> </code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Relevance extension introduces the following element. === The "score" element === Contains a string indicating a relative assessment of relevance for a particular search result with respect to the search query. Decimal values less than 0 should be considered equal to 0. Decimal values greater than 1 should be considered equal to 1. Unparseable or empty values can be ignored by the client. : Restrictions: The value must contain a decimal representation of a real number between 0 and 1, inclusive. : Requirements: This element may appear zero or one time. The <code>score</code> element is used to indicate a relative assessment of relevance for a particular search result with respect to the search query. ''Examples of <code>score</code> elements:'' <relevance:score>0.3</relevance:score> <relevance:score>0.924</relevance:score> <relevance:score>0.12</relevance:score> == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1634 2006-08-11T16:26:10Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Relevance/1.0]] moved to [[Specifications/OpenSearch/Extensions/Relevance/1.0/Draft 1]] == Notice == {{Draft notice}} == Introduction == The OpenSearch Relevance Extension allows search engines indicate a relative score in a particular domain for an individual search result. ''Example of a search result that includes a relevance score:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:relevance="<nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <relevance:score>0.95</relevance:score> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Relevance Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki> </code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Relevance extension introduces the following element. === The "score" element === Contains a string indicating a relative assessment of relevance for a particular search result with respect to the search query. Decimal values less than 0 should be considered equal to 0. Decimal values greater than 1 should be considered equal to 1. Unparseable or empty values can be ignored by the client. : Restrictions: The value must contain a decimal representation of a real number between 0 and 1, inclusive. : Requirements: This element may appear zero or one time. The <code>score</code> element is used to indicate a relative assessment of relevance for a particular search result with respect to the search query. ''Examples of <code>score</code> elements:'' <relevance:score>0.3</relevance:score> <relevance:score>0.924</relevance:score> <relevance:score>0.12</relevance:score> == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1714 2006-09-05T20:53:45Z DeWitt 2 Protected "[[Specifications/OpenSearch/Extensions/Relevance/1.0/Draft 1]]" [edit=sysop:move=sysop] == Notice == {{Draft notice}} == Introduction == The OpenSearch Relevance Extension allows search engines indicate a relative score in a particular domain for an individual search result. ''Example of a search result that includes a relevance score:'' <feed xmlns="<nowiki>http://www.w3.org/2005/Atom</nowiki>" xmlns:opensearch="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:relevance="<nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki>"> <nowiki><!-- ... --></nowiki> <entry> <title>New York History</title> <link href="<nowiki>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</nowiki>"/> <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> <relevance:score>0.95</relevance:score> </entry> <nowiki><!-- ... --></nowiki> </feed> == Namespace == The XML namespace of the OpenSearch Relevance Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/relevance/1.0/</nowiki> </code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch response. == Elements == The OpenSearch Relevance extension introduces the following element. === The "score" element === Contains a string indicating a relative assessment of relevance for a particular search result with respect to the search query. Decimal values less than 0 should be considered equal to 0. Decimal values greater than 1 should be considered equal to 1. Unparseable or empty values can be ignored by the client. : Restrictions: The value must contain a decimal representation of a real number between 0 and 1, inclusive. : Requirements: This element may appear zero or one time. The <code>score</code> element is used to indicate a relative assessment of relevance for a particular search result with respect to the search query. ''Examples of <code>score</code> elements:'' <relevance:score>0.3</relevance:score> <relevance:score>0.924</relevance:score> <relevance:score>0.12</relevance:score> == Author == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Suggestions 1439 1568 2006-08-09T16:10:24Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Suggestions]] moved to [[Specifications/OpenSearch/Extensions/Suggestions/1.0]] #REDIRECT [[Specifications/OpenSearch/Extensions/Suggestions/1.0]] Specifications/OpenSearch/Extensions/Suggestions/1.0 1432 1549 2006-08-09T15:26:27Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of the Firefox 1550 2006-08-09T15:30:29Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. 1566 2006-08-09T16:10:04Z DeWitt 2 /* Authors */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1567 2006-08-09T16:10:24Z DeWitt 2 [[Specifications/OpenSearch/Extensions/Suggestions]] moved to [[Specifications/OpenSearch/Extensions/Suggestions/1.0]] == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. 1577 2006-08-09T16:28:08Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1717 2006-09-05T20:54:18Z DeWitt 2 Protected "[[Specifications/OpenSearch/Extensions/Suggestions/1.0]]" [edit=sysop:move=sysop] == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Suggestions/1.1 1679 2126 2008-10-02T00:11:42Z DeWitt 2 Redirecting to [[Specifications/OpenSearch/Extensions/Suggestions/1.1/Draft 1]] #REDIRECT [[Specifications/OpenSearch/Extensions/Suggestions/1.1/Draft_1]] Specifications/OpenSearch/Extensions/Suggestions/1.1/Draft 1 1677 2090 2008-10-01T22:40:47Z DeWitt 2 New page: == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given... == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2091 2008-10-01T22:41:57Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2092 2008-10-01T22:57:35Z DeWitt 2 /* OpenSearch Description document */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: "sears","search engines","search engine","search","sears.com","seattle times" ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2093 2008-10-01T23:01:21Z DeWitt 2 /* Completions */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears","search engines","search engine","search","sears.com","seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: <nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki> === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2094 2008-10-01T23:01:31Z DeWitt 2 /* Query URLs */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears","search engines","search engine","search","sears.com","seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2095 2008-10-01T23:02:00Z DeWitt 2 /* Completions */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results" ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2096 2008-10-01T23:02:26Z DeWitt 2 /* Descriptions */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2097 2008-10-01T23:02:53Z DeWitt 2 /* Query URLs */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: <nowiki>["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]</nowiki> == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2098 2008-10-01T23:05:06Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>] ] == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2100 2008-10-01T23:24:11Z DeWitt 2 /* Background */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes a [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>] ] == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2101 2008-10-01T23:24:28Z DeWitt 2 /* Overview */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>] ] == Authors == Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2102 2008-10-01T23:25:19Z DeWitt 2 == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>] ] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2103 2008-10-01T23:27:24Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>] ] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2104 2008-10-01T23:28:38Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location, offset from 0, within the list of search suggestions. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2105 2008-10-01T23:29:58Z DeWitt 2 /* The "suggestionRank" parameter */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2106 2008-10-01T23:30:56Z DeWitt 2 /* Completions */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''oq={suggestions:suggestionPrefix?}''' &amp;'''aq={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2107 2008-10-01T23:32:56Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionRank" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionRank</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionRank</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''rank={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2108 2008-10-01T23:36:00Z DeWitt 2 /* The "suggestionRank" parameter */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''rank={suggestions:suggestionRank?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2109 2008-10-01T23:36:15Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation]. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2110 2008-10-01T23:41:12Z DeWitt 2 /* Background */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response will contain search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2111 2008-10-01T23:42:22Z DeWitt 2 /* Type */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Response == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2112 2008-10-01T23:43:05Z DeWitt 2 /* Search Suggestions Response */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Responses in JSON == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2113 2008-10-01T23:44:08Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Search suggestions URL example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Responses in JSON == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2114 2008-10-01T23:44:23Z DeWitt 2 /* Query Parameters */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Search suggestions URL example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Additional Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Example === Example of a Url template that requests additional information when used to perform a suggested search. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <Url type="application/x-suggestions+json" template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Responses in JSON == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2115 2008-10-01T23:45:21Z DeWitt 2 /* Example */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch Description document == Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query. === URL elements === <code>Url</code> elements of <code>type="application/x-suggestions+json"</code> should be used by the client to retrieve search suggestions. === Search suggestions URL example === Example of publishing the location of a search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Additional Query Parameters === The OpenSearch Refinement Extension introduces the following parameters that can be requested by search engines to provide additional context about the search suggestions that led to the current search query. === The "suggestionPrefix" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === The "suggestionIndex" parameter === When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. === Search Query Example === Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Responses in JSON == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2116 2008-10-01T23:54:05Z DeWitt 2 /* OpenSearch Description document */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == Search Suggestions Responses in JSON == === Response Format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response Content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Query String ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Completions ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2117 2008-10-01T23:55:57Z DeWitt 2 /* Search Suggestions Responses in JSON */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2118 2008-10-01T23:59:51Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2119 2008-10-02T00:03:28Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2120 2008-10-02T00:05:17Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2121 2008-10-02T00:06:50Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. These extension parameters could be used in any Url template, but are only defined here when they are used in the context of a follow-up query to a suggested search. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2122 2008-10-02T00:07:09Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. These extension parameters could be used in any Url template, but there meaning is defined here only when they are used in the context of a follow-up query to a suggested search. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2123 2008-10-02T00:08:17Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. These extension parameters could be used in any Url template, but there meaning is defined here only when they are used in the context of a follow-up search query generated from a list of suggested searches. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2124 2008-10-02T00:08:37Z DeWitt 2 /* Declaring a URL for follow-up search queries */ == Notice == {{Draft notice}} == Introduction == The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. == Background == The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters. == Overview == The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query. == Type == The following type is used to indicate that the response contains JSON formatted search suggestions: : <code>application/x-suggestions+json</code> == Namespace == The XML namespace of the OpenSearch Suggestions Extension is: : <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == OpenSearch description document == Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries. === Declaring a JSON-formatted search suggestion URL === Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format. ==== Example ==== Example of publishing the location of a JSON-formatted search suggestion query: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"> '''<Url type="application/x-suggestions+json"''' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>''' <nowiki><!-- ... --></nowiki> </OpenSearchDescription> === Declaring a URL for follow-up search queries === After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine. The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration. These extension parameters could be used in any Url template, but the meaning is defined here only when they are used in the context of a follow-up search query generated from a list of suggested searches. ==== The "suggestionPrefix" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== The "suggestionIndex" parameter ==== When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0. Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension. ==== Example ==== Example of a Url template that accepts additional information when used in conjunction with suggested searches: <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''> <Url type="text/html" template="<nowiki>http://example.com?q={searchTerms}</nowiki> &amp;'''prefix={suggestions:suggestionPrefix?}''' &amp;'''index={suggestions:suggestionIndex?}"'''/> <nowiki><!-- ... --></nowiki> </OpenSearchDescription> == JSON-formatted search suggestion responses == === Response format === The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays. === Response content === Search suggestions are returned as an ordered collection of values. The four values are returned in the following order: * Query String * Completions * Descriptions * Query URLs ==== Suggestion prefix ==== Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response. Required: yes Example: "sea" ==== Search terms ==== Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search. Required: yes Example: ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"] ==== Descriptions ==== Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. Required: no Example: ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"] ==== Query URLs ==== Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists. Required: no Example: [<nowiki>"http://example.com?q=sears", "http://example.com?q=search+engines", "http://example.com?q=search+engine", "http://example.com?q=search", "http://example.com?q=sears.com", "http://example.com?q=seattle+times"</nowiki>] === Example === The following is a full example of a JSON formatted search suggestions response: ["sea", ["sears", "search engines", "search engine", "search", "sears.com", "seattle times"], ["7,390,000 results", "17,900,000 results", "25,700,000 results", "1,220,000,000 results", "1 result", "17,600,000 results"], [<nowiki>"http://example.com?q=sears"</nowiki>, <nowiki>"http://example.com?q=search+engines"</nowiki>, <nowiki>"http://example.com?q=search+engine"</nowiki>, <nowiki>"http://example.com?q=search"</nowiki>, <nowiki>"http://example.com?q=sears.com"</nowiki>, <nowiki>"http://example.com?q=seattle+times"</nowiki>]] == Authors == This specification was edited by DeWitt Clinton <dewitt@opensearch.org>, based on the work of Joe Hughes' search suggestions documentation in Firefox and the Google search suggestions format. == License == This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Specifications/OpenSearch/Extensions/Time/1.0/Draft 1 1587 1919 2007-06-15T19:59:59Z AndrewTurner 66 Creating Time Extension Page http://example.com/?q={searchTerms}&dtstart={dtstart}&dtend={dtend} dtstart ~ rfc2445 (2007-02-12T04:30:02Z) 1921 2007-06-15T20:17:33Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchtime="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: : <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === : <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={opensearchtime:start}&dtend={opensearchtime:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc2445.txt RFC-2445 - Internet Calendaring and Scheduling Core Object Specification], or more commonly known as 'iCalendar', standard. It is of the format : <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> : <code><nowiki>2007-02-12T04:30:02Z</nowiki></code> Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1922 2007-06-15T20:18:19Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchtime="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={opensearchtime:start}&dtend={opensearchtime:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc2445.txt RFC-2445 - Internet Calendaring and Scheduling Core Object Specification], or more commonly known as 'iCalendar', standard. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>2007-02-12T04:30:02Z</nowiki></code> Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1923 2007-06-15T20:36:07Z AndrewTurner 66 Added dtend example == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchtime="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={opensearchtime:start}&dtend={opensearchtime:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc2445.txt RFC-2445 - Internet Calendaring and Scheduling Core Object Specification], or more commonly known as 'iCalendar', standard. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>2007-02-12T04:30:02Z</nowiki></code> Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1929 2007-07-23T17:13:04Z AndrewTurner 66 /* The "start" and "end" parameters */ == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:opensearchtime="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={opensearchtime:start?}&dtstart={opensearchtime:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={opensearchtime:start}&dtend={opensearchtime:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1930 2007-07-27T16:39:49Z AndrewTurner 66 Changed namespace from opensearchtime to just time. == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtstart={time:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtstart={time:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 1936 2007-08-16T02:24:46Z AndrewTurner 66 == Notice == {{Draft notice}} == Introduction == Geospatial data is becoming increasingly available as the tools for specifying and sharing location are more ubiquitous and easy to use. The purpose of the OpenSearch-Geo extensions is to provide a standard mechanism to query a resource based on geographic extents, or location name. The geospatial results are based on the GeoRSS standards. Therefore, latitude/longitude order, bounding box parameters, and polygon are all using that standard. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2243 2009-08-07T18:53:24Z AndrewTurner 66 Modifying to talk about Time and not Geo == Notice == {{Draft notice}} == Introduction == As the amount of historic data builds on the web, it is valuable to provide a way for users and tools to easily query based on time and timespans. The purpose of the OpenSearch-Time extensions is to provide a standard mechanism to query a resource based on temporal extents. The Temporal parameters are based on the iCalendar and Microformat standards. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept geospatial search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2244 2009-08-07T18:53:43Z AndrewTurner 66 /* Example */ == Notice == {{Draft notice}} == Introduction == As the amount of historic data builds on the web, it is valuable to provide a way for users and tools to easily query based on time and timespans. The purpose of the OpenSearch-Time extensions is to provide a standard mechanism to query a resource based on temporal extents. The Temporal parameters are based on the iCalendar and Microformat standards. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:stop?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2357 2010-02-15T17:49:42Z AndrewTurner 66 Fixing the incorrect usage of time:stop for the correct time:end based on feedback from Chris Lynnes. == Notice == {{Draft notice}} == Introduction == As the amount of historic data builds on the web, it is valuable to provide a way for users and tools to easily query based on time and timespans. The purpose of the OpenSearch-Time extensions is to provide a standard mechanism to query a resource based on temporal extents. The Temporal parameters are based on the iCalendar and Microformat standards. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:end?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:end?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] 2358 2010-02-15T17:51:49Z AndrewTurner 66 Adding link to the iCalendar specification Wikipedia page. == Notice == {{Draft notice}} == Introduction == As the amount of historic data builds on the web, it is valuable to provide a way for users and tools to easily query based on time and timespans. The purpose of the OpenSearch-Time extensions is to provide a standard mechanism to query a resource based on temporal extents. The Temporal parameters are based on the [http://en.wikipedia.org/wiki/ICalendar iCalendar] and Microformat standards. === Namespace === Updated July 27, 2007: the OpenSearch Time extension namespace was shortened to just "time" instead of "opensearchtime". This was to make the namespace more succint. == Example == Example of a detailed OpenSearch description document that describes a search engine that accept temporal search parameters. <?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>" xmlns:time="<nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki>"> <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="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:end?}&pw={startPage?}&format=atom</nowiki>"/> <Url type="text/html" template="<nowiki>http://example.com/?q={searchTerms}&dtstart={time:start?}&dtend={time:end?}&pw={startPage?}</nowiki>"/> <LongName>Example.com Web Search</LongName> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</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> == Namespace == The XML namespace of the OpenSearch Time Extension is: <code><nowiki>http://a9.com/-/opensearch/extensions/time/1.0/</nowiki></code> This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document. == Parameters == === The "start" and "end" parameters === <code><nowiki>http://example.com/?q={searchTerms}&pw={startPage?}&dtstart={time:start}&dtend={time:end}&format=rss</nowiki></code> Replaced with a string of the beginning of the time slice of the search query. This string should match the [http://www.ietf.org/rfc/rfc3339.txt RFC-3339 - Date and Time on the Internet: Timestamps], which is also used by the [http://www.ietf.org/rfc/rfc4287.txt Atom syndication format]. It is of the format <code><nowiki>YYYY-MM-DDTHH:mm:ssZ</nowiki></code> <code><nowiki>1996-12-19T16:39:57-08:00</nowiki></code> 'Z' is the time-offset, where 'Z' signifies UTC or an actual offset can be used. Example: <nowiki>http://example.com/?q=news&dtstart=2007-02-12T04:30:02Z&dtend=2007-03-11T02:28:00Z&format=rss</nowiki> == Author == Andrew Turner <ajturner@highearthorbit.com> == Contributors == DeWitt Clinton <dewitt@opensearch.org> == License == This document is made available subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License]. [[Category:Specification]] [[Category:Extension]] Todo list 1466 1702 2006-09-05T15:28:49Z DeWitt 2 [[Todo list]] moved to [[Community/Todo list]] #REDIRECT [[Community/Todo list]]