SRU

Introduction

SRU (Search/Retrieve via URL) is a standard search protocol for Internet search queries, utilizing CQL (Common Query Language) and standard query syntax for representing queries. In the context of libraries, SRU is mainly used for search and retrieval of bibliographic records from the catalog.

Alma gives institutions the ability to be a SRU target. The following core SRU operations are supported in Alma:

• explain
• searchRetrieve

The base URL for SRU requests is: https://<Alma domain>/view/sru/<institution code>

Note: an institution must turn on the SRU target functionality. By default, it is not enabled. This is done by defining an “SRU” external profile in Alma. Refer to the Alma online help for more information. In addition, an institution might decide to include availability information as part of the response. Refer to the Alma online help for more information regarding the ‘include availability’ setup.

Explain operation

The explain operation allows a client to retrieve a description of the facilities available at an SRU server. It can then be used by the client to self-configure and provide an appropriate interface to the user. The response includes a list of all the searchable indexes. These are the indexes that are configured by the institution as allowed in the ‘Advanced Search’ in Alma. They can be used for the searchRetrieve operation. Sortable indexes have a “sort=true” indication.

Note that each institution might configure a different set of indexes.

Note that the use of indexes of different inventory in the same search query is not supported.

For example, a search query with barcode and service ID will not return any results.

Request

For example: https://<Alma domain>/view/sru/<institution_code>?version=1.2&operation=explain

Response

See explain response from Alma’s Guest sandbox

SearchRetrieve operation

The searchRetrieve operation is the main operation of SRU. It allows the client to submit a search and retrieve request for matching records from the server.

Request

For example: https://Alma domain/view/sru/institution_code?version=1.2&operation=searchRetrieve&recordSchema=marcxml&query=alma.all_for_ui=history

CQL queries 

An SRU search statement is expressed in CQL syntax.

Common Query Language

(CQL) is a formal language for representing queries to information retrieval systems such as web indexes, bibliographic catalogs, and museum collection information. The design objective is that queries be human-readable and writable and that the language be intuitive while maintaining the expressiveness of more complex languages.

A CQL query is made up of a single search clause, or multiple search clauses connected by Boolean operators. Each search clause consists of the following components: Index, Relation, and a Search term.

• The searchable indexes are listed in the explain operation response and are the indexes that are supported in Alma’s advanced search.
• Relation operators supported by SRU, which are aligned with the Alma advanced search, are:
  • For all index fields both ‘=’ (contains phrase) and ‘all’ (contains words) relations are supported.
  • For search indexes that are numeric, dates or range the ‘<’ (less than), ‘>’ (greater than), ‘<=’ (less than and equal), ‘>=’ (greater than and equal), ‘==’ (equals), ‘<>’ (not equals) relations are supported.
  • The ‘*’ can be used as a wild card with the ‘all’ operator. For example, “title all World*” [find records where the title contains a string of: “World”, eg. “World history”].
  • In order to search for an empty string Alma supports the use of ==””. For example, title==”” [find records where the title is empty].
  • The ‘==’ operator can also be used to search for a phrase that includes a dash or an underline.
• The search terms must be enclosed in double quotes if they contain any of the following characters: < > = / ( )  and whitespace.

Excluding Suppressed Records

By default an SRU search returns also suppressed records.

The query can be limited to only return non-suppressed records by adding “alma.mms_tagSuppressed=false” to the search query.

For example:  query=alma.issn=1234%20and%20alma.mms_tagSuppressed=false

Sort

In order to retrieve a sorted list of records, sortBy should be sent as part of the query. The sort specification is included at the end of the CQL query, in the following format:

sortBy index/sort.descending or sortBy index/sort.ascending

For example: <base url>?version=1.2&operation=searchRetrieve&recordSchema=marcxml&query=alma.title=t sortBy alma.title/sort.descending

The indexes that can be used for sorting are those with sort=”true” indication in the explain response.

Response

The response to an SRU searchRetrieve request is an XML document. The table below provides a summary and description of the elements provided by the XML document:

Note: Suppressed records are not returned as part of the SRU response.

Electronic resources managed in the Network Zone

In a consortia environment, electronic resources can be managed on behalf of the members in the Network Zone. It is possible to retrieve the bibliographic records and inventory information that are managed in the Network Zone and are available for the specific member. For this purpose, the configuration option “Include results of e-resources managed in the Network” is available in the SRU integration profile. For more information please refer to the OLH.

Data Enrichment: identifiers
The bibliographic record retrieved from Alma is enriched with additional identifiers: The MMS ID of the Network Zone and the Alma Community Zone ID are added to the record in additional 035 marc fields. The Community Zone ID is added with the prefix (EXLCZ) while the Network Zone ID is added with the prefix (EXLNZ-network_code). The local MMS ID is in the 001 marc field. These additional shared IDs can be used for better identification of a common record. The local MMS ID should be used when there is a need to call an API in the institution for the record.

For DCMI family records (dc, dcx), the MMS ID is added to dc:identifier using the following structure: alma:institution_code/bibs/mms_id

Data Enrichment: availability

It is possible to configure Alma to return availability information as part of the SRU response. Enrichment is as returned by the GET BIB API.

See SRU response with availability sample

Examples (in Alma’s Guest sandbox environment):

• searchRetrieveResponse – This is a search operation, for keywords = history. Only 3 records should be returned in the response, from the fourth to the sixth record.
• searchRetrieveResponse with error – This is a search operation, using non existing index.

See SRU in the Guest sandbox for more details.

Important Note: The SRU integration is intended for integrating Alma search with other automated systems for the purposes of inter-library loan, copy catalog, or selection. Using the SRU integration for other workflows, such as performing bulk exports of records, is not supported. Therefore it is possible to retrieve up to 10,000 records for a single search.