Libris ILL API - documentation

Introduction

Libris is the swedish national union catalogue. It contains about 7 million bibliographic records from swedish academic and research libraries, as well as some public libraries. In addition to cataloguing and search services, Libris provides an ILL service for making interlibrary loan requests between its member libraries.

The following is a description of the API to the Libris ILL system. The primary function of the API is to enable libraries to import data from Libris to the their local library system (ILS) and other automation systems. The API also provides a few functions that updates the Libris ILL system.

This document will briefly describe the data content, but in order to fully understand the system, it's probably best to first get acquainted with the actual live system.

Note on the documentation

For best result, append a library code to the page url.

/librisfjarrlan/api/doc/[library_code]

When this documentation page is generated, some "live" data is fetched. If the page is called with an added library code some data, such as the last request for the library, usable date intervals, etc, is fetched from the database. This should make most of the links actually genererate real data to review. If no library code is provided, the library code SEK is used. This is not guaranteed to yield any actual results since this library code is used by Libris for internal testing.

Formats

Output

The Libris ILL API is accessed by calling certain urls over http.

For example: /librisfjarrlan/api/illrequests/SEK/incoming

The API outputs data in the following formats: JSON, PDF, XML and text. To make it simple, the preferred format is selected by appending the parameter format=[format] to the url (format=json | format=pdf | format=xml | format=text). If this parameter is omitted, the output format will be JSON.

JSON

JSON (javascript object notation) is the default format. It is the only format that always is implemented. (For certain API calls a default "not implemented" message will be sent for the other formats.)

PDF

The PDF format is used by the Libris ILL system internally for printing purposes. Not all data is formatted for PDF output. The format is provided, for those cases when the printing function in the Libris ILL system is not well adjusted for the local workflow. The API can be called directly, for instance, to generate PDF pages at timed intervals.

XML

In the previous API (called Libris ILL export functions) XML was the default format. The data structure has changed between the versions, so this can not be used as a replacement for the older version. Since the XML output need some additional data mangling it is not guaranteed to always contain all the data that is found in the JSON output. If possible, use JSON instead.

Text (YAML)

The very first version of the Libris ILL export functions used a simple line-based text format, that was replaced fairly quickly with the XML format. This format is not compatible with the old text format, but similar. It uses YAML, so it's easy to implement a parser. It's provided mostly for proof-reading, since it's slightly more human-readable than JSON. The text (YAML) output will likely always contain the same data as the JSON output , but is, as is the XML output, a bit experimental, and should not be the first choice.

Input

The API provides a few functions to do small updates to the Libris ILL database. Although the API is based on REST principles, the legacy structure of the Libris ILL database makes it impossible to implement a full-fledged REST solution. For updates, only HTML form data (application/x-www-form-urlencoded) can be used.

Form data

For most read functions there is no corresponding write function. When there is, the API expects normal form data to be posted (HTTP method POST, not PUT) and a parameter named "action". When performing updates, the current timestamp for the data (normally found in the field "last_modified") also must be sent. Before any update is performed the timestamp is checked against the database to make sure no updates to the data has been done between the time the data was fetched and the update.

An example: to mark an ill request as "read", two parameters need to be set: timestamp to the current timestamp and action to "read". The data is then posted to the same url that was used to fetch the ill request. (See more details in the section ILL data update.)

Authentication

Authentication is done by sending a key in a custom http header, "api-key", with each request. The key can be appended to the url as well (api-key=1223211), but this feature will be removed after an inital testing phase. This key must be obtained from Libris. The API can also be tested in a browser if a login to the Libris ILL system has been successfull. The authentication key is connected to the organisation level in the Libris library database (http://bibdb.libris.kb.se), so ILL data for all libraries within the same organisation is available with one key.

(The authentication method may be changed in the future, so if possible, see to that is relatively easy to modify this in the calling application.)

ILL data

All data available through the different views in the Libris ILL application can be retrieved via the API. This includes ILL requests, user requests, users and library information.

ILL requests (/illrequests)

The base url for retrieving ill requests is constructed as follows:

/librisfjarrlan/api/illrequests/SEK/[result type | request id]

The first part is the data type, the second is the code for the library and third part is either a "result type", that is, view, that is based on the current status of the requests in the database or an exact id for a specific request, regardless of status. The id could either be the numeric database id or the constructed ill reference number ("lf_number"), which has the format [library_code]-YYMMDD-NNNN, for example SEK-130528-0001.

If the parameter media_type=[loan | copy] is added to the url, the result is filtered on the specified media type. For example:

/librisfjarrlan/api/illrequests/SEK/recent?media_type=loan

/librisfjarrlan/api/illrequests/SEK/recent?media_type=copy

ILL request (/12345)

/librisfjarrlan/api/illrequests/SEK/6623030

Retrieves the ILL request with the given database id.

ILL request (/SEK-240126-0001)

/librisfjarrlan/api/illrequests/SEK/SEK-240126-0001

Retrieves the ILL request with the given Libris ILL reference number.

Incoming requests (/incoming)

/librisfjarrlan/api/illrequests/SEK/incoming

Incoming requests are requests to the specified library from other libraries. These requests have either the status "Uteliggande" ("outstanding") or "Remitterad" ("forwarded"). In the Libris ILL application the workflow is as follows: the request is checked against the local library system. If the material is available the request is marked as "read" and placed in a print queue (to create a picking list). If it is out on loan, missing, etc, a response is sent to the system and the request moves to next recipient (if any) or sent back to requester.

Recent requests (/recent)

/librisfjarrlan/api/illrequests/SEK/recent

Returns incoming requests with status "Uteliggande", "Remitterad" and "Läst" from the last 5 workdays.

Reservations (/reservations)

/librisfjarrlan/api/illrequests/SEK/reservations

Reservations are requests with the status "Reservation". When the receiving library is unable to fullfill a request, it can add to the response that the material may be reserved at the library, if it isn't obtainable from any other library in the recipient list. The requesting library will in this case select a library to place the reservation at. These reservation requests is then picked up by the selected library and are either performed or rejected (it might no longer be possible to reserve the material at this point.)

Cancellations (/cancellations)

/librisfjarrlan/api/illrequests/SEK/cancellations

When an ILL request has been marked as "read" at the active library, it is possible that the material already has been delivered. Therefore the requester cannot simply delete the request. Instead it's get the status "Avbeställd" (cancelled) and can be retrieved by the active library. The library can then check the local status and either actually delete the request in the Libris ILL database, or inform the requester that the material is on its way.

Archive (incoming) (/incoming_archive)

/librisfjarrlan/api/illrequests/SEK/incoming_archive?start_date=2024-01-12&end_date=2024-01-26

Given a starting and an ending date in the format YYYY-MM-DD this will retrieve all incoming request between the two dates. Libraries with a lot of incoming requests should be a little careful with the span of the date interval.

Outgoing requests (/inbox)

/librisfjarrlan/api/illrequests/SEK/inbox

Outgoing requests can be retrieved in different ways. The inbox contains all outgoing requests that have had a status change. The status change resets the xstatus to "Ej läst" ("Not read"). Note that the xstatus must be set manually to "Läst" ("Read") in the Libris ILL application or via the API. For libraries with a lot of outgoing requests, it may be impractical to use the inbox.

Reservation possible (/may_reserve)

/librisfjarrlan/api/illrequests/SEK/may_reserve

The material has been impossible to obtain from any library in the recipient list, but one or more libraries have responded that it can be reserved for the requesting library.

Not fullfilled (/notfullfilled)

/librisfjarrlan/api/illrequests/SEK/notfullfilled

The material has been impossible to obtain from any library in the recipient list.

Delivered (/delivered)

/librisfjarrlan/api/illrequests/SEK/delivered

The material has been delivered to the requesting library. Note that not all libraries set the status to "Levererad" ("Delivered"). Statistically, Libris considers a request with the status "Läst" ("Read") that has not been modified for 30 days to be fullfilled (i.e. the material has been delivered).

Archive (outgoing) (/outgoing)

/librisfjarrlan/api/illrequests/SEK/outgoing?start_date=2024-01-12&end_date=2024-01-26

Given a starting and an ending date in the format YYYY-MM-DD this will retrieve all outgoing request between the two dates. Libraries with a lot of outgoing requests should be a little careful with the span of the date interval.

Most recent request (/last)

/librisfjarrlan/api/illrequests/SEK/last

/librisfjarrlan/api/illrequests/SEK/last?operator=PGREN

Retrieves the most recent request made by the library. When the parameter operator is added to the url, it retrieves the most recent request made by that operator at the library.

User requests

Libris has a service which enables end users to create an account in Libris Websearch and ask their library to make ILL requests for material they've found in Libris. The following calls make it possible for the library to retrieve these requests. (Note:if the library which is specified in the urls does not accept user requests all results will be empty.)

User request (/userrequests/12345)

/librisfjarrlan/api/userrequests/SEK/497199

Returns a Libris end user request for the specified id. The library code must match the library the request was sent to.

Outstanding user requests (/userrequests)

/librisfjarrlan/api/userrequests/SEK

This returns all outstanding user requests sent to the library. They have the status "Väntar" ("Waiting") or "Under arbete" ("Under process").

User requests by user (/userrequests)

/librisfjarrlan/api/userrequests/SEK?user_id=55168

Returns all requests made by the specified user.

Archive (user requests) (/userrequests)

/librisfjarrlan/api/userrequests/SEK?start_date=2023-11-11&end_date=2023-12-11

Given a starting and an ending date in the format YYYY-MM-DD this will return all user requests made between the two dates, regardless of whether they've been accepted or rejected.

Library information

The Libris ILL application uses a subset of the data that is stored in the Libris library database, the parts that are relevant to the ILL functions. This data can be retrieved with this API, but if more data about a given library is needed, the Libris Library database has its own API.

For consistency with the other calls as well as for authentication, the library code for the calling library must be given as well. This may be a little confusing.

Library information (/[library_code])

/librisfjarrlan/api/libraries/SEK/SEK

This returns library information (address, email, etc) for the given library code.

Multiple libraries (/[library_code,library_code, ...])

/librisfjarrlan/api/libraries/SEK/G,H,L

This returns library information (address, email, etc) for the libraries in the comma separated list of library codes.

All libraries (/all_libraries)

/librisfjarrlan/api/libraries/SEK/all_libraries

This returns library information (address, email, etc) for the libraries in the Libris ILL database. This should not be used too frequently.

ILL data update

This API allows a small amount of the Libris ILL database to be updated. Updates are performed by posting form data to certain urls. The timestamp found in the field last_modified must always be present. That is, before a post is made, the data that is to be updated must first be fetched with a get request and the current value of the field last_modified obtained.

Note that the changes to the database made by these updates here are mostly irreversible (there is currently no "undo" function in the Libris ILL application).

ILL request (/12345)

/librisfjarrlan/api/illrequests/SEK/6623030

The actual data to update depends on the parameter action. With the update the timestamp retrieved from data field last_modified must be sent.

action=read

Parameters:

This will do one of two things. If the request originated from the library, this will only set the xstatus to "Läst" ("Read"). If it is an incoming request, the ILL status is changed from "Uteliggande" or "Remitterad" to "Läst" ("Outstanding" or "Forwarded" to "Read").

action=reserve

Parameters:

Depending of the value of "reserve" this will either set the request status to "Reserverad" ("Reserved") - if the value is equal to 1 - or to "Negativt svar" ("Not fullfilled"), if the value is 0.

action=cancel

Parameters:

Depending of the value of "cancel" this will either set the request status to "Makulerad" ("Deleted") - if the value is equal to 1 - or to "Ej avbeställd!" ("Not cancelled"), if the value is 0.

action=response

Parameters:

Pre-defined response codes:

This will send a response to the Libris ILL system. This will either move the request to next library in the recipient list or set its status to "Negativt svar" ("Not fullfilled"). In order to make a response that does not fit any of the available codes, set the response_id to 8 (Övrigt) and use the added_response to add a descriptiion of the problem with the request. The added response can also be used in addition to any of the other response codes. For instance, add a date when the material is to be recalled, if it is on loan. Set may_reserve to 1 to let the requesting library know if the material can be reserved on a unsuccessful return.