SRU service

Introduction

The OED SRU service (search/retrieve via URL) provides a means to automate basic queries, using a standard syntax to represent queries, and a standard protocol for returning results. For more information on SRU standards, see www.loc.gov/standards/sru/.

Results are returned in XML using the Dublin Core (DC) schema (see www.dublincore.org). This makes the service appropriate for federated searching and similar automated query tasks.

Please note that the OED SRU service is subject to abuse detection, and heavy use may result in your account being suspended. We recommend that you limit use to 30 queries per minute.

Transport

The SRU service provides only HTTP transport; SOAP is not available. The service URL is http://www.oed.com/srupage.

Syntax and examples

The function of the SRU service is similar to that of a normal Quick Search query. The main parameter is a query string (a word or phrase). Headwords and lemmas that match the query string are returned as result records.

A simple query takes the following form (where test is the query string):

http://www.oed.com/srupage?operation=searchRetrieve&query=cql.serverChoice+=+test&maximumRecords=100&startRecord=1

As in normal Quick Search, query handling is insensitive to case, diacritics, spaces, and hyphens (more).

Wildcards

Wildcards may be used, as in normal Quick Search queries:

http://www.oed.com/srupage?operation=searchRetrieve&query=cql.serverChoice+=+*ize&maximumRecords=100&startRecord=1

Multi-word queries

Multi-word query strings should be quoted:

http://www.oed.com/srupage?operation=searchRetrieve&query=cql.serverChoice+=+%22mountain+g*%22&maximumRecords=100&startRecord=1

Single-word query strings may be quoted, but it is not necessary to do so.

maximumRecords and startRecord parameters

The maximumRecords parameter sets an upper limit to the number of records returned. The maximum effective value is 100. Values over 100 are treated as equivalent to 100.

The startRecord parameter specifies the first record that will be returned. This provides a means to ‘page’ through large numbers of result records; e.g. if there are 15 results in total, then startRecord=5&maximumRecords=5 will return records 5—10.

If the startRecord value is higher than the total number of records, a diagnostic message ‘Parameter value out of range’ is returned.

Records

Records returned by a SRU query correspond to the set of results returned by a normal Quick Search query. Each record is contained in a <srw:record> element. The key components of each record are:

• dc:title: the entry headword (and lemma, where relevant).
• dc:identifier: the ID of the entry, in the form /Entry/1234.
• dc:description: an HTML-formatted version of the dictionary definition (automatically truncated in the case of long definitions).

To construct the full entry URL, the dc:identifier value should be appended to the base URL http://www.oed.com/view, to give e.g. http://www.oed.com/view/Entry/1234.

The SRU service only ever returns result records, not the entries themselves. In the event that a query matches a single entry, a single result record is returned. (This behaviour is different from normal Quick Search, where a query returning a single result will take the user directly to the entry.)

If there are no results, the XML returned will contain the single element <srw:numberOfRecords>0</srw:numberOfRecords>, with no records. No alternative suggestions, nearest matches, etc., are returned.

SRU conformance

The service implements SRU version 1.2 (see www.loc.gov/standards/sru/specs/ for full specifications). In order to provide some backward-compatiblity, it also accepts requests identified as SRU 1.1, although 1.1 features that have been removed from 1.2 are not supported (these features are marked version 1.1 only in the specifications).

The service implements the two required SRU operations: searchRetrieve and explain. It does not implement the scan operation.

The OED SRU provides a single result schema: DC (Dublin Core).

The following SRU parameters are not supported:

• recordPacking = string (only XML is supported)
• persistent result sets (as requested by resultSetId, resultSetTTL)

CQL conformance

The OED SRU makes use of the org.z3950.zing.cql CQL Parser and provides full level 1 conformance; see www.loc.gov/standards/sru/specs/cql.html.

A single index is provided: cql.serverChoice. According to the CQL specification, cql.serverChoice is the default when no index is specified; in this implementation that is equivalent to performing an OED Quick Search. Results are sorted alphabetically.

The following operators, indexes, relations, and modifiers defined by the CQL Context Set version 1.2 are not supported:

• sortby operator
• == operator
• > operator
• < operator
• >= operator
• <= operator
• <> operator
• adj relation
• all relation
• any relation
• within relation
• encloses relation
• prefix assignment
• resultSetId index
• allRecords index
• allIndexes index
• anyIndexes index
• keywords index

No modifiers are supported.