|
|
General
A9.com Integration
The OpenSearch formats
- Why should I support OpenSearch?
-
Publishing your search results in OpenSearch™ format will draw more people to your content,
by exposing it to a much wider audience through aggregators such as A9.com.
- My site doesn't have a search engine. Can A9.com index my content and offer OpenSearch results?
-
Not at this time, but please send us feedback and
let us know what you think A9.com could do that would be useful for you.
- How do I test and validate my OpenSearch documents?
-
OpenSearch Responses in RSS and Atom formats can be tested as you would normally test RSS and Atom feeds.
The Feed Validator is highly recommended.
To test the OpenSearch Description file, and how it fits together with the Response, visit the OpenSearch submission page on A9.com.
You can try it out without actually submitting it to A9. Here are some things to remember to check for:
- accuracy of the information and correct spelling
- your logo is showing up properly, if you have specified one
- the sample search works; other searches work
- searches that return zero results work
- bad/malformed searches work
- pagination (viewing multiple pages of search results) works, if you have enabled this functionality
- How do I add my search engine to A9.com?
-
Visit the OpenSearch submission page and enter the URL of your OpenSearch Description file.
You should also use that page to test that it works properly before submitting it to A9.com.
- How do I update my search engine on A9.com?
-
If you need to make changes to your OpenSearch Description file, do so, and then resubmit the file on the OpenSearch submission page.
If you were the person who originally submitted the file (and you are signed in), you can also find your search from the list
by going to that page and selecting “Columns You’ve Created” from the “Show” menu and clicking on the “Update” link beside your search engine.
-
It is recommended that you do not change the URL of the OpenSearch Description file, as it is used to identify the feed.
If changed, users of A9.com who have been searching on it, will now find that it is gone.
If you must change it, submit the file at its new address, and delete the old one.
-
If you need to make changes to your OpenSearch Response, you can just go ahead and do that, and the changes will be seen immediately.
If you are worried about the changes causing problems, you could create a new OpenSearch Description file that points to the new response, test that out on A9.com,
and if it works okay, use those changes on the original OpenSearch, and delete the test one.
- How do I remove my search engine from A9.com?
-
Follow the instructions for updating your search engine to get to the submission page, but instead of submitting the column, click “Delete this column permanently.”
If you are not signed in to A9.com with the account of the person who submitted the search engine, you will need to change the OpenSearch Description file’s
SyndicationRight
to closed or private. Note that once you make this change, anyone will be able to delete the search engine from A9.com.
- Does A9.com support all of OpenSearch?
-
A9.com supports nearly all of OpenSearch, with few exceptions.
OpenSearch is quite flexible, and has capabilities beyond what it makes sense to use on A9.com.
While OpenSearch Description files may specify results in any format, A9.com only uses results in OpenSearch Response format.
The
POST HTTP method is not supported.
-
The
Query element is one of the most flexible parts of OpenSearch.
It can theoretically be used anywhere, which is of course impossible to support.
Currently A9.com uses Query in two ways: with a
role of example an an OpenSearch Description,
and with a role of correction, related, subset, or superset
in an OpenSearch Response, both for the results as a whole, and within individual search results.
Only the searchTerms search parameter is used at this time.
-
OpenSearch Description files can specify any type of response (HTML, RSS, Atom, etc.).
However, RSS and Atom responses are two specifically extended by OpenSearch.
As to which to use, that is up to you; both are perfectly acceptable, and you can even produce both.
RSS is a simpler format than Atom, while Atom is a stricter format with other advantages.
A9.com supports both RSS 2.0 and Atom 1.0; other clients can choose to support whichever formats they want.
Remember, OpenSearch Description files can specify multiple response formats, however they should be listed in order of priority for OpenSearch readers to use.
- Can I use HTML?
-
Yes, search results may include HTML, although some OpenSearch clients may remove it (see more about this on OpenSearch Tips).
The Atom specification describes how to use HTML in Atom. For RSS, here is how A9.com handles it:
-
HTML in RSS item descriptions should be either HTML-encoded (one time) or be enclosed in a CDATA section.
An example of each follows, showing the word ‘cat’ bolded:
<description>picture of my <b>cat</b></description>
<description><![CDATA[ picture of my <b>cat</b> ]]></description>
- My service supports more structured queries than “searchTerms.” How do I handle that?
-
Many services support advanced query syntaxes, such as ISBN numbers for books, or regular expressions.
There is a simple way you can enable this with OpenSearch, allowing your feed to be used by clients that do understand those types of queries, and those that don’t.
-
Using parameter extensibility, use an existing vocabulary, or create your own, and add a new search parameter with it.
Then make both
{searchTerms} and the new parameter optional (by using ?).
Most clients will not understand the new parameter, so they will supply searchTerms; those that do understand will instead supply the new parameter.
Here is how part of the OpenSearch Description might look:
-
<Url type="application/rss+xml" xmlns:books="http://example.com/book-vocabulary"
template="http://example.com/search?q={searchTerms?}&isbn={books:isbn?}" />
- See the Query Syntax specification for more.
- Why doesn’t OpenSearch support feature X?
-
The OpenSearch specification was intentionally designed to be functional yet minimal.
Most features that you want should be possible with the extensibility mechanisms in the specification.
Additional functionality will likely be made available in future versions; we love to hear your input.
To participate in the forum where the future of OpenSearch is discussed, visit the OpenSearch Mailing List.
-
As it turns out, you can already do a tremendous amount within the current RSS/Atom-based title, link, and summary/content/description tags.
If you have sponsored links, for example, feel free to place them as a search result.
One thing to remember is that users usually don’t mind sponsored links—as long as you are clear about which results are which.
Try changing the formatting around for them and including a few words to that effect.
-
A search result could include a URL to generate a map, or to a list of images, or to phone book entries.
Use your imagination—there a million great searches out there just waiting to be opened to the world.
- Why are all the elements capitalized?
-
Capitalization for version 1.1 is the same as in 1.0, for consistency.
- Why does OpenSearch have its own
<link /> element, rather than using Atom’s?
-
The
link element in Atom uses a formal list of allowable rel values.
The appropriate value for OpenSearch is search, and until this is a valid value for Atom, it will not be used in Atom.
See also the General OpenSearch FAQ, Developer How-to and OpenSearch Tips.
|
