Article DOI/PMID Lookup Endpoint Quick Start Guide (LibKey)
- John Seguin
The LibKey API is a powerful tool designed for developers to quickly leverage the linking power of LibKey in a variety of applications. This guide is a quick start to get you going and some advice on best practices for implementation, but for additional details we recommend you also look at the Article DOI/PMID Lookup Endpoint Reference Guide as well.
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 key pieces of information:
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
In return, you get:
bestIntegratorLink for a simple point of interaction defining the best way to get to content for that particular 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:
Click the LibKey Link → Organization’s SSO → Content
Thus if an organization’s SSO already has an activate session LibKey links have the potential (when they indicated “Download PDF” to be literally “one click to content!”
Examples
If you haven’t done so already, contact support@thirdiron.com to confirm your Library_ID and API_KEY which you need to try the following 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}
These queries will yield similar JSON results like this using this open access example which you can use, substituting 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:
{
"data": {
"id": 558922648,
"type": "articles",
"title": "Genotyping by sequencing for estimating relative abundances of diatom taxa in mock communities",
"date": "2023-02-06",
"authors": "Çiftçi, Ozan; Wagemaker, Cornelis A. M.; Mertens, Adrienne; van Bodegom, Peter; Pirovano, Walter; Gravendeel, Barbara",
"inPress": false,
"abandoned": false,
"doi": "10.1186/s12862-023-02104-2",
"linkResolverOpenUrl": "http://um9mh3ku7s.search.serialssolutions.com/?genre=article&aulast=%C3%87ift%C3%A7i&issn=2730-7182&title=BMC%20Ecology%20and%20Evolution&atitle=Genotyping%20by%20sequencing%20for%20estimating%20relative%20abundances%20of%20diatom%20taxa%20in%20mock%20communities&volume=23&issue=1&spage=4&epage=&date=2023&doi=10.1186%2Fs12862-023-02104-2&sid=LibKey",
"pmid": "36747145",
"o