Article DOI/PMID/ID Lookup Endpoint Quick Start Guide (LibKey)

The LibKey API lets developers integrate LibKey's full-text linking into any application via a simple RESTful GET request. This guide covers the basics and best practices; see the Article DOI/PMID Lookup Endpoint Reference Guide for full detail.

Overview

In short, the interaction between your application and the LibKey API is a RESTful interaction featuring a simple GET request to the API with three required parameters plus one optional:

• DOI/PMID (for identifying the article you are interested in learning about)

• Library ID (for identifying for which library the links are intended)

• API Key (unique to the library ID)

• (optional) an “include” statement which allows you to receive journal-level information as well

Open

In return, you get:

• bestIntegratorLink - the pre-calculated best URL to full text for that organization

• OA Status - for defining if the article is OpenAccess. You might use this to display some sort of “open access” icon in your interface, for example.

• Article in context link (browzineWebLink) if you would like to provide a link to see the article in its originally published context within the BrowZine interface (all LibKey subscribers have access to BrowZine web as well which is needed for this link to appear/work).

• Detailed breakdown of all available links (with the “best” one already pre-calculated in the aforementioned “bestIntegratorLink” value)

• (If using the optional include) Information about the journal including a link to the journal in BrowZine and link to the cover image asset for inclusion in your interface as well as the SJR value of the journal.

The User Experience

So what happens when a user clicks a LibKey.io link that the API returns for “Download PDF” or “Article Link?” These are the content links designed to get the user directly to the content in an authorized way via their institution. While all LibKey links have a similar syntax they wind up forwarding to completely different URL’s based on the outcome of the LibKey link calculations. The most common user workflow however looks like this:

If the user already has an active SSO session, a "Download PDF" link can deliver content in a single click.

Examples

To setup a query, using your API Key use this kind of structure for DOIs:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/doi/{DOI}?access_token={API_KEY}

… and this kind of structure for PMIDs:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/pmid/{PMID}?access_token={API_KEY}

… and this kind of structure for Third Iron Article IDs:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/id/{ArticleId}?access_token={API_KEY}

All query types return JSON like the following. You can test this using the open access example below (substitute your own API Key):

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/doi/10.1186/s12862-023-02104-2?access_token={API_KEY}

You should JSON that looks something like this:

bestIntegratorLink

The full response is documented in the reference guide, but we recommend all integrators start with bestIntegratorLink.

bestLink - The recommended URL to show users based on the priority order discussed in detail in the table below

linkType - The type which then corresponds to the same element in the more verbose response that appears before bestIntegratorLink.

linkCategory - Presently, only two types: “alert” means it is warning the user of something about the article before presenting the user linking options. All of the links in this category will result in a detail page at the LibKey.io domain as shown in the examples below. “link” means the link will forward the user to where the content can be accessed or requested.

recommendedLinkText - This is the recommended English-language text for this experience. This text aligns as the default text for thousands of customers in other Third Iron produced products. This can be customized if this text conflicts with your product/service’s general design.

Below is a table defining the current different link types, categories and recommended text and the order in which they are presented as the “bestLink”. (e.g. If fullTextFile is available, then this will be presented but if it is not and contentLocation is available, then contentLocation will appear as the linkType).

Priority Order Number	linkType	linkCategory	Description and Sample Screenshot of user experience (Assuming the user is ALREADY authenticated. If not, depending on the article, the user may first account an SSO login or prompt to turn on VPN, etc. for their organization)	recommendedLinkText

Priority Order Number	linkType	linkCategory	Description and Sample Screenshot of user experience (Assuming the user is ALREADY authenticated. If not, depending on the article, the user may first account an SSO login or prompt to turn on VPN, etc. for their organization)	recommendedLinkText
1	retractionNoticeUrl	alert	A notification that the article has been retracted Open Retraction information landing page within LibKey. Further links are presented to learn more or access full text.	Retracted Article
2	expressionOfConcernNoticeUrl	alert	A notification that the article has an expression of concern on it Open Expression of Concern information landing page within LibKey. Further links are presented to learn more or access full text.	Expression of Concern
3	problematicJournalArticleNoticeUrl*	alert	A notification that the article is associated with a journal produced by a publisher that Third Iron has assessed as problematic. Open Problematic Journal information landing page within LibKey. Further links are presented to learn more or access full text.	Problematic Journal
4	fullTextFile	link	A link to the PDF file Open Most often a PDF will appear directly in the browser window. Open Some publishers instead initiate an automatic download of the file instead of showing it in the browser. This is a publisher’s server configuration. Open Uncommonly, some publishers will display the PDF within a branded frame set but the PDF will still be immediately viewable.	Download PDF
5	contentLocation	link	A link to the landing page for this article Open Typically, a PDF is one click away and/or the HTML of the text is visible.	View Article
6	documentDeliveryFulfillmentUrl*	link	A link to the library’s unmediated document delivery provider Open A two-step process of landing on Article Galaxy Scholar and inputting your email to receive a copy as well as immediately be shown a copy of the paper.	Request PDF
7	linkResolverOpenUrl	link	A link to the library’s Link Resolver URL for this article Resulting link screenshot example: Open Exact UI will be different based on library link resolver provider and settings within LibKey but typically will present routes to view print holdings, access ILL and document delivery services or perform other actions.	Access Options

Optional Include to get Journal Information

You can optionally do an include (e.g. “include=journal”) to get journal information including the cover image for the journal. For the above example you would tweak the call to look like this:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/doi/10.1186/s12859-023-05326-9?include=journal&access_token={API_KEY}

Now, you can see the response looks like this:

Importantly are these two elements for implementation consideration: