Bookmarklet API

What is the bookmarklet API?

The bookmarklet API allows you to pass partial or full bibliographic data about a resource to Talis Reading Lists. 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 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 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:

http://lists.broadminsteruniversity.org/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:

http://lists.broadminsteruniversity.org/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

AttributeDescription
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 formatrft_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:

AttributeDescription
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.

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.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk