What is the bookmarklet API?
The bookmarklet API allows you to pass partial or full bibliographic data about a resource to Talis Aspire Reading Lists (TARL). The system can then use this data to construct a full resource for your user, ready to add to a list.
If you only have partial information about a resource (say in the case of a book, you only have the ISBN) you can send this to the bookmarklet API and Talis Aspire Reading Lists will search a number of sources and attempt to construct a full metadata record, linked to your library catalogue.
What can it be used for?
You can use the bookmarklet API to create deeplinks into the Talis Aspire Reading Lists bookmarking workflow, allowing users with just one click to add resources from within your library catalogue, search system, portal, link resolver or anywhere else.
I’m not a developer, how do I get my system vendor to do this?
- Ask the vendor of your system to add a link to their product which is built like the examples in this bookmarkletAPI document
- The vendor will need to place this bookmark link somewhere in their system and make sure that the information in the openURL part of the bookmark link is dynamically constructed based on the content of the page that the link is present on.
- That’s it. It’s up to you and the vendor to work out whether this is a possible solution.
- Talis will be happy to provide technical advice to the vendor if required. Please contact us via the support desk.
I am a developer, how do I use the API?
To use the API, simply construct a link complete with OpenURL 1.0 attributes representing a full or partial description of the resource you’d like your users to be able to bookmark. OpenURL is an industry standard already supported by a number of vendors in a range of software tools.
The Bookmarklet endpoint is always constructed as follows:
http://<tenancyBaseUrl>/ui/forms/bookmarklet.html?<openUrlParams>
An example of the endpoint being used to pass in the ISBN of a resource:
https://broadminster.rl.talis.com/ui/forms/bookmarklet.html?rft.isbn=0003223566
You can supply as much or as little data as you’d like, and when your link is clicked, the system will attempt to provide a full record by matching the data supplied against various data sources including your local library catalogue, Open Library and the complete CrossRef dataset.
If a full record cannot be found, the API simply presents the user with any information passed via the OpenURL attributes.
In the example above (from our demo system), we can see that a full record is returned to the user with author, title, publisher date etc.
If you have more metadata, you can pass it:
https://broadminster.rl.talis.com/ui/forms/bookmarklet.html?rft.issue=11/12&rft.volume=41&rft.date=2007&rft.issn=0309-0566&rft.spage=1306&rft.atitle=Developing+a+scale+for+stakeholder+orientation&rft.jtitle=Journal+of+Informatics
In this case, due to the combination of attributes, the Bookmarklet API recognises that you are describing a Journal Article, and splits up the resource assigning the title, pages, issue and volume information to the article entity, and the jtitle and ISSN to a journal part:
COinS
If your system is already able to create Context Objects in Spans (COinS) then you simply need to use the same content of the COinS title attribute as the parameters to pass to the bookmarklet API.
Full List of recognised OpenURL 1.0 attributes
| Attribute | Description |
|---|---|
rtf.atitle |
Title of an individual item (article, part of book e.g. chapter, preprint, conference proceeding) |
rft.au |
Author name. To pass multiple authors, use rft.au[], e.g. rft.au[]=Joe Blogs&rft.au[]=Jim Bloggs |
rft.aufirst |
First name of author |
rft.aulast |
Surname of author |
rft.btitle |
Title of book. If an rft.atitle also exists, assume the resource is a chapter which is part of a book |
rft.date |
Date of publication |
rft.edition |
Edition |
rft.eissn |
Electronic ISSN |
rft.issn |
ISSN |
rft.isbn |
ISBN (10 or 13) |
rft.issue |
Issue |
rft.volume |
Volume |
rft.jtitle |
Journal title. If there is an rft.atitle assume the resource is an article which is part of a journal |
rft.place |
Place of publication |
rft.pub |
Publisher |
rft.spage |
Start page |
rft.epage |
End page |
rft.title |
Title |
rft.genre |
Recognised values are book, chapter or article (upper or lower case). |
rft.title |
Title |
rft_id |
Can be used to pass other identifiers. DOIs can be passed in the format rft_id=info:doi/10.1348/026151008X334728
|
Legacy attributes
The API will also support a more basic set of non-OpenURL attributes, including the library catalog number, as follows:
| Attribute | Description |
|---|---|
isbn |
ISBN |
doi |
Digital Object Identifier. Pass in the format doi=10.1348/026151008X334728 |
bibid |
Library catalog number - this will almost guarantee that we’ll find the record in your library system. If we see this identifier, then we’ll try this first before trying any other identifiers in the open url parameters. |
uri |
A web address for this resource. It will appear in the field "Web addresses", and should be urlencoded. |
Where legacy attributes and their OpenURL equivalents are passed, the OpenURL versions take precedence.
Why does the API ignore my attributes?
If the API is passed enough information to find an authoritative record, i.e. via your library catalogue, or the publisher-submitted metadata at CrossRef, Aspire will preference that data over any data provided in the API call. Therefore, things like exact titles and author names may differ in the resulting data presented to the user for bookmarking.
This can be overridden by the user simply by amending the details in the split bookmarking view before adding the bookmark.
Examples in use
Richard Cross at NTU uses this API in the Ex Libris SFX Target Parser for Talis Aspire.
NTU have also been working on a better integration for customers using ExLibris’ Primo which will use this API.