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.READ MORE IN THE BLOGS
Alma gives institutions the ability to be a SRU target. The following core SRU operations are supported in Alma:
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.
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.
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.
|Parameter name||Mandatory /Optional||type||Description|
|version||Mandatory||string||SRU protocol version. Should be ‘1.2’|
|operation||Mandatory||string||The specific SRU operation. Should be ‘explain’|
For example: https://<Alma domain>/view/sru/<institution_code>?version=1.2&operation=explain
|record||Mandatory||string||A single explain record, wrapped in the record metadata fields.|
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.
|Parameter name||Mandatory /Optional||type||Description|
|version||Mandatory||string||SRU protocol version. Should be ‘1.2’ [version 1.1 is available but deprecated]|
|operation||Mandatory||string||The specific SRU operation. Should be ‘searchRetrieve’|
|query||Mandatory||string||Contains a query expressed in CQL to be processed by the server. See below for more info on CQL queries supported in Alma.|
|startRecord||Optional||number||The 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.|
|maximumRecords||Optional||number||The number of records requested to be returned. The value must be 0-50. Default: 10|
|recordSchema||Optional||string||The schema requested for the records to be returned.|
Currently, the supported values are:
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
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 ‘==’ operator can also be used to search for a phrase which 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
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: <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.
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:
|version||Mandatory||string||1.2 [version 1.1 is available but deprecated]|
|numberOfRecords||Mandatory||number||The number of records matched by the query. If the query fails this will be 0.|
|Records||Optional||sequence of||A 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.|
|diagnostics||Optional||sequence of||A 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.
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
Examples (in Alma’s Guest sandbox environment):
- searchRetrieveResponseThis 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 errorThis 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. Therefor it is possible to retrieve up to 10,000 records for a single search.