Item linking API

The item linking API allows you to answer the question “Which lists have this resource on it?”

What is the Item linking API?

The item linking API allows you to discover where an item is used within Talis Aspire. Suppose you have a book with a given ISBN, and you want to find out which lists in Talis Aspire reference the book. You can do that with the item linking API.

What can it be used for?

You could use this API to extend your library OPAC or discovery tool, building a widget that shows which lists items are on.

Your library systems vendor may be able to incorporate this API to allow a check and alert that a resource that is about to be withdrawn is on your reading list.

How do I use the API?

To use the API, all you have to do is build a special URI. Given this URI, Talis Aspire Reading Lists will return a set of list names and URIs in JSON format.

The API supports ISSN, ISBN10, ISBN13, local control numbers/catalogue IDs (LCN) or DOIs. Put simply, start with one of these, and then build it into the URI used to call the API. Let’s try an example with ISBN “0596000278”:

To call the API use either of the following two URIs:

The following JSON data is returned:

"": "Copy of new list with import citations",
"": "new list with import citations"

NB: This API handles ISBN10 to ISBN13 conversion for you. So, a request for the ISBN10 “0070167265” will also return matches for 9780070167261. There is no need to do two calls (they will return exactly the same results).

Here are some other examples, using DOI and LCN (note that both of these will give a valid 404 response):

What if there are no lists found for the identifier given?

You will get a HTTP 404 NOT FOUND response. Any application that you develop using this API should expect to handle the 404 as a valid response condition meaning that the Talis Reading Lists tenancy did not contain any data which matched that requested.

The callback parameter and JSONP

If the API is called from Javascript within the browser, you’ll need to use a JSONP callback parameter to avoid the cross-domain scripting security model. For more information on JSONP, see this Wikipedia article.

The API supports the query string parameter “cb” to specify the callback function. The callback function must be a valid function in your calling code that will handle the JSON data returned on a successful request. For example:

Wraps the response as a parameter of the “foo” method:

"": "Copy of new list with import citations",
"": "new list with import citations"

Who can use this API?

Anyone can use this API, although excessive requests will be rate limited though, except by prior arrangement.

Typical Implementation

These steps outline the typical way in which this API might be used.

  • The library catalogue which the user is using has an area where custom functionality can be inserted using javascript.
  • The user is viewing a resource such as a book in a library catalogue.
  • The user will see additional information to tell them that the resource appears on a reading list.
  • The javascript code will:
    • Build a URL as outlined above which includes the LCN or ISBN or DOI of the resource being viewed. It will typically specify a callback function, and make a non blocking asynchronous JSONP request.
    • If the request to the API returns a 404 NOT FOUND, then there are no lists with that resource on. Exceptions should be handled graceful and not block or halt other javascript code that may be running on the page.
    • If the item does exist, the typical implementation will provide a clickable link to take the user to the list.
  • It should be expected that there could be many results returned. In the case of popular study resources, these may appear on many hundreds of lists.

Examples of this API in use

Nottingham Trent University

Richard Cross at NTU has developed RELIC (REsourceListItemChecker) to help with the item acquisitions process. The service makes use of this API to show which lists an item is on within NTU’s Talis Aspire Reading Lists implementation. See

The University of Sussex

Tim Graves at the University of Sussex used this API to add 'cited on' links to their Primo Explore catalogue.

Have more questions? Submit a request


Please sign in to leave a comment.