OpenSearch service

From refbase

This document describes the refbase OpenSearch service.

Contents

OpenSearch

refbase-0.9.5 or greater supports the OpenSearch standard which is a collection of simple formats for the sharing of search results.

The Wikipedia entry for OpenSearch explains OpenSearch as follows:

"OpenSearch is a collection of technologies that allow publishing of search results in a format suitable for syndication and aggregation. It is a way for websites and search engines to publish search results in a standard and accessible format."

OpenSearch-enabled clients can automatically discover refbase's OpenSearch service, and use a standardized search syntax (CQL) to retrieve results in standardized formats. Users of OpenSearch-enabled browsers can search refbase directly from their browser's toolbar, and refbase can provide search suggestions while the user types a search term in the browser's search box (example screenshot).

About the refbase OpenSearch implementation and usage examples

This section explains the refbase OpenSearch service and gives some working examples (based on these records) of an online refbase server:

Autodiscovery

All refbase web pages feature an OpenSearch autodiscovery link in the HTML <head>:

<link rel="search" type="application/opensearchdescription+xml" title="refbase Beta Database" href="http://beta.refbase.net/opensearch.php?operation=explain">

This informs an OpenSearch-enabled client about the URL of the OpenSearch description document which is a simple XML format that describes the required URL syntax and lists the response formats offered by the refbase server. Example:

opensearch.php?operation=explain

URL syntax

The refbase OpenSearch service requires the query parameter to be present in the OpenSearch request. By default, the keywords field will be queried, and results will be returned in Atom XML format together with the OpenSearch response elements. Example:

opensearch.php?query=Baltic

One can also query other fields (for details, see below), in this example we'll query the title field instead:

opensearch.php?query=dc.title=Baltic

For each record, the refbase Atom XML response includes direct links to export & citation formats, OpenURL & unAPI links, Dublin Core metadata, as well as the formatted citation. This makes it an ideal candidate for mashups, especially since there are already many libraries that facilitate parsing of OpenSearch Atom results. The Atom format can be also displayed out of the box by any good feed reader (example screenshot).

In addition, the refbase OpenSearch service also offers HTML, RSS, SRW_DC XML and SRW_MODS XML as response formats:

opensearch.php?query=dc.title=Baltic&recordSchema=html
opensearch.php?query=dc.title=Baltic&recordSchema=rss
opensearch.php?query=dc.title=Baltic&recordSchema=srw_dc
opensearch.php?query=dc.title=Baltic&recordSchema=srw_mods

The SRU URL parameters startRecord, maximumRecords and stylesheet are also supported for the refbase OpenSearch service.

By default, refbase will return as many records as specified by the admin in variable $defaultNumberOfRecords in file initialize/ini.inc.php. You can use the startRecord and maximumRecords parameters to explicitly define the first record and the maximum number of records that shall be returned. This allows clients to page thru the result set. As an example, compared to the above queries, the following query will retrieve the next five records from the result set:

opensearch.php?query=dc.title=Baltic&startRecord=6&maximumRecords=5

If the stylesheet parameter wasn't given in the query, the SRW_DC XML and SRW_MODS XML formats will be served with a default stylesheet so that they can be viewed more easily in a web browser. However, you can suppress any stylesheets by including the stylesheet parameter without a value:

opensearch.php?query=dc.title=Baltic&recordSchema=srw_dc&stylesheet=
opensearch.php?query=dc.title=Baltic&recordSchema=srw_mods&stylesheet=

Query syntax

Similar to the refbase SRU web service, the OpenSearch service supports CQL as search syntax, i.e. you can use a CQL query as the value of the query parameter. See the "Help & Examples" section of the refbase OpenSearch web form for a short overview of the supported CQL syntax. Here are a few examples that show different CQL queries:

opensearch.php?recordSchema=html&query=dc.creator any Mill* Grad*
opensearch.php?recordSchema=html&query=dc.title all Snow Antarct*
opensearch.php?recordSchema=html&query=bath.issn exact 0022-1430

Search suggestions

The refbase OpenSearch gateway can return search suggestions. This allows OpenSearch-enabled browsers (such as Firefox) to present search suggestions for search terms entered in the browser's search box.

Clients can request search suggestions from a refbase server by including operation=suggest in the URL request. Here's an example that returns suggestions in JSON format:

opensearch.php?query=author=Gre&operation=suggest&recordSchema=json

refbase can also return HTML-formatted search suggestions (in form of an unordered list):

opensearch.php?query=author=Gre&operation=suggest&recordSchema=html