Ready to Learn?Ex Libris products all provide open APIs

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 a "SRU" external profile in Alma. Refer to the Alma online help for more information.
In addition, 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 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.

Request
Parameter nameMandatory /OptionaltypeDescription
versionMandatorystringSRU protocol version. Should be '1.2'
operationMandatorystringThe specific SRU operation. Should be ‘explain’

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

Response

ElementMandatory /OptionaltypeDescription
versionMandatorystring1.2
recordMandatorystringA single explain record, wrapped in the record metadata fields.

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
Parameter nameMandatory /OptionaltypeDescription
versionMandatorystringSRU protocol version. Should be '1.2'
operationMandatorystringThe specific SRU operation. Should be 'searchRetrieve'
queryMandatorystringContains a query expressed in CQL to be processed by the server. See below for more info on CQL queries supported in Alma.
startRecordOptionalnumberThe position within the sequence of matched records of the first record to be returned. The first position in the sequence is 1. The value supplied must be greater than 0. Default: 1.
maximumRecordsOptionalnumberThe number of records requested to be returned. The value must be 0 -50. Default: 10
recordSchemaOptionalstring

The schema requested for the records to be returned. Currently, the supported values are marcxml, dc, unimarcxml, kormarcxml and cnmarcxml. Supported schemas are listed in the schemaInfo section of the explain document.

Note: when there is no crosswalk between formats the returned format is the one the record was originally created in.

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

 

CQL queries 

A 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 which are        supported in Alma 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 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 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: ?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: 
ElementMandatory /OptionaltypeDescription
versionMandatorystring1.2
numberOfRecordsMandatorynumberThe number of records matched by the query. If the query fails this will be 0.
RecordsOptionalsequence ofA sequence of records matched by the query or surrogate diagnostics. As the currently supported schema is marcxml, the records must be returned according to the marc21 xml schema format.
diagnosticsOptionalsequence ofA sequence of non-surrogate diagnostics generated during execution, in case the request failed. The structure includes the following fields:
uri – error number
Message – error related message See diagnostic.xsd
Note: Suppressed records are not returned as part of the SRU response.

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.

SRU record fetch

Data Enrichment: availability

It is possible to configure Alma to return availability information as part of the SRU response. Availability information is stored in the AVA (physical availability), AVE (electronic availability) and AVD (digital availability) fields. The data in each field is the same as returned by the GET BIB API.
Examples (in Alma's Guest sandbox environment):

 

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.