List linking API

This article explains how the list linking API answers the question “Which lists are there for my Module?”

What is the List linking API?

The list linking API allows you to find a list or set of lists that are attached to a given point on the Talis Aspire Reading Lists hierarchy, using a calculable/guessable URI structure. The hierarchy is the tree of courses and programmes at your institution. Read more about how the hierarchy is updated.

What can it be used for?

Using this API, you can develop a widget or extension for your Learning Management System, to direct students on a course or module page direct to the correct lists within Talis Aspire Reading Lists.

How do I use the API?

This API can be used in two forms, simple or advanced. Both forms rely on adding extra path information onto the end of the hierarchy URI.

In both cases, you can get the information back as HTML, RDF/XML or JSON as per the same principles outlined in our Linked data API specification.

When used in HTML mode, the API shows a table of available lists for the user to choose from. If there is only one list linked to a matching hierarchy node, Talis will redirect to that list rather than show the table. This feature allows you to provide guessable links direct to reading lists within your Learning Management System.

Simple (without time periods)

In this mode, simply take the hierarchy URI and append either “/lists”, “/lists.json” or “/lists.rdf” onto the end of it. For example, let’s start with

By default, if you do not specify a time period, you will receive all lists attached to the hierarchy node regardless of time period.

IMPORTANT: Node codes must be lower case in the URI

Advanced (with time periods)

If you have time periods configured, you can instruct the API only to return lists for a given module within a given active time period (i.e. semester or term). For a description of time periods and how they work, please read the time periods article.

To do this, add the time period slug onto the end of the URI, for example:

The slug usually takes the defined time period title, replacing all ‘spaces’ with a ‘-‘ and removing all symbols (note that a ‘-‘ is not treated as a symbol and will be preserved in the slug). For example ‘Semester 1&2, 2011-12’ becomes ‘Semester-1-2-2011-12’.

The slug is configurable though - so if you need it to match a specific string that your learning management system knows, then just raise a support ticket asking us to do this for you.


The API supports JSONP to get around Cross Site Scripting issues. You can specify a callback function, using the cb parameter:

Who can use this API?

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

This API is used in both the Moodle and Blackboard integrations. Read more about our learning management system integrations.


Have more questions? Submit a request


Please sign in to leave a comment.