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:
Links to the PDF (fullTextFile) and Article Link (contentLocation) if available
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).
(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.
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://api.thirdiron.com/public/v1/libraries/{Library_ID}/articles/doi/{DOI}?access_token={API_KEY}
… and this kind of structure for PMIDs:
https://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://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": 573087326,
"type": "articles",
"title": "Reducing Boolean networks with backward equivalence",
"date": "2023-05-23",
"authors": "Argyris, Georgios A.; Lluch Lafuente, Alberto; Tribastone, Mirco; Tschaikowski, Max; Vandin, Andrea",
"inPress": false,
"abandoned": false,
"doi": "10.1186/s12859-023-05326-9",
"ILLURL": "https://illiad.mst.edu/illiad/illiad.dll/OpenURL?genre=article&aulast=Argyris&issn=1471-2105&isbn=&title=BMC%20Bioinformatics&atitle=Reducing%20Boolean%20networks%20with%20backward%20equivalence&volume=24&part=&issue=S1&spage=212&epage=&date=20231201",
"pmid": "37221494",
"openAccess": true,
"unpaywallUsable": true,
"fullTextFile": "https://libkey.io/libraries/222/articles/573087326/full-text-file?utm_source=api_29",
"contentLocation": "https://libkey.io/libraries/222/articles/573087326/content-location?utm_source=api_29",
"availableThroughBrowzine": true,
"startPage": "212",
"endPage": "",
"browzineWebLink": "https://browzine.com/libraries/222/journals/74/issues/520079562?showArticleInContext=doi:10.1186%2Fs12859-023-05326-9&utm_source=api_29",
"relationships": {
"issue": {
"links": {
"related": "/public/v1/libraries/222/issues/520079562"
}
},
"journal": {
"links": {
"related": "/public/v1/libraries/222/journals/74"
}
}
},
"abstract": "Boolean Networks (BNs) are a popular dynamical model in biology where the state of each component is represented by a variable taking binary values that express, for instance, activation/deactivation or high/low concentrations. Unfortunately, these models suffer from the state space explosion, i.e., there are exponentially many states in the number of BN variables, which hampers their analysis.\nWe present Boolean Backward Equivalence (BBE), a novel reduction technique for BNs which collapses system variables that, if initialized with same value, maintain matching values in all states. A large-scale validation on 86 models from two online model repositories reveals that BBE is effective, since it is able to reduce more than 90% of the models. Furthermore, on such models we also show that BBE brings notable analysis speed-ups, both in terms of state space generation and steady-state analysis. In several cases, BBE allowed the analysis of models that were originally intractable due to the complexity. On two selected case studies, we show how one can tune the reduction power of BBE using model-specific information to preserve all dynamics of interest, and selectively exclude behavior that does not have biological relevance.\nBBE complements existing reduction methods, preserving properties that other reduction methods fail to reproduce, and vice versa. BBE drops all and only the dynamics, including attractors, originating from states where BBE-equivalent variables have been initialized with different activation values The remaining part of the dynamics is preserved exactly, including the length of the preserved attractors, and their reachability from given initial conditions, without adding any spurious behaviours. Given that BBE is a model-to-model reduction technique, it can be combined with further reduction methods for BNs."
}
}
There is a lot of information there which you might consider utilizing and that which is covered in detail in the reference guide here but to get you started the most important elements are listed below including recommended order of usage:
Property | Type | Description | Optional |
|---|---|---|---|
retractionNoticeUrl | URL | Will appear if the article has been retracted with a link to a LibKey.io URL which provides more information about the retraction with data from Retraction Watch. This field is optional but we recommend looking for this element FIRST and displaying this URL instead of or in addition to a “fullTextFile” or “contentLocation” link so that users can be made aware of the retraction status of the article they are viewing. | Yes |
fullTextFile | URL | On articles where LibKey is aware of a path directly to the PDF file, this property will be available. Look for this next and display it if there is no Retraction Notice available. | Yes |
contentLocation | URL | On articles where LibKey is aware of a path to the web page where the article is available, this property will be available. This can include non-publisher sources such as aggregators and repositories. Sometimes articles will have a fullTextFile AND a contentLocation and other times ONLY a contentLocation. Depending on your goals you may choose to display only one (typically prefering fullTextFile) or BOTH of these to give users options. | Yes |
openAccess | boolean | True if the article is open access via the publisher and False if it is not. LibKey.io links corresponding to this article which have an openAccess value of "True" will not include any institutional authentication. You may wish to make use of this if you want to display an “Open Access” badge or icon of some kind next to the article. | No |
browzineWebLink | URL | On titles that are BrowZine enabled, this property will be present and will link to the article in the context of its issue (or articles in press list as appropriate) on browzine.com You may wish to make use of this if you want to provide an article in context experience into BrowZine. A popular integration point in all of the commercially available discovery systems (Primo, Summon, EDS, OCLC WorldCat, Discovery, TDNet Discovery, etc.) | No |
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://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:
{
"data": {
"id": 573087326,
"type": "articles",
"title": "Reducing Boolean networks with backward equivalence",
"date": "2023-05-23",
"authors": "Argyris, Georgios A.; Lluch Lafuente, Alberto; Tribastone, Mirco; Tschaikowski, Max; Vandin, Andrea",
"inPress": false,
"abandoned": false,
"doi": "10.1186/s12859-023-05326-9",
"ILLURL": "{ILL LINK WOULD APPEAR HERE IF CONFIGURED AT YOUR LIBRARY}",
"pmid": "37221494",
"openAccess": true,
"unpaywallUsable": true,
"fullTextFile": "https://libkey.io/libraries/222/articles/573087326/full-text-file?utm_source=api_29",
"contentLocation": "https://libkey.io/libraries/222/articles/573087326/content-location?utm_source=api_29",
"availableThroughBrowzine": true,
"startPage": "212",
"endPage": "",
"browzineWebLink": "https://browzine.com/libraries/222/journals/74/issues/520079562?showArticleInContext=doi:10.1186%2Fs12859-023-05326-9&utm_source=api_29",
"relationships": {
"journal": {
"links": {
"related": "/public/v1/libraries/222/journals/74"
}
},
"issue": {
"links": {
"related": "/public/v1/libraries/222/issues/520079562"
}
}
},
"abstract": "Boolean Networks (BNs) are a popular dynamical model in biology where the state of each component is represented by a variable taking binary values that express, for instance, activation/deactivation or high/low concentrations. Unfortunately, these models suffer from the state space explosion, i.e., there are exponentially many states in the number of BN variables, which hampers their analysis.\nWe present Boolean Backward Equivalence (BBE), a novel reduction technique for BNs which collapses system variables that, if initialized with same value, maintain matching values in all states. A large-scale validation on 86 models from two online model repositories reveals that BBE is effective, since it is able to reduce more than 90% of the models. Furthermore, on such models we also show that BBE brings notable analysis speed-ups, both in terms of state space generation and steady-state analysis. In several cases, BBE allowed the analysis of models that were originally intractable due to the complexity. On two selected case studies, we show how one can tune the reduction power of BBE using model-specific information to preserve all dynamics of interest, and selectively exclude behavior that does not have biological relevance.\nBBE complements existing reduction methods, preserving properties that other reduction methods fail to reproduce, and vice versa. BBE drops all and only the dynamics, including attractors, originating from states where BBE-equivalent variables have been initialized with different activation values The remaining part of the dynamics is preserved exactly, including the length of the preserved attractors, and their reachability from given initial conditions, without adding any spurious behaviours. Given that BBE is a model-to-model reduction technique, it can be combined with further reduction methods for BNs."
},
"included": [
{
"id": 74,
"type": "journals",
"title": "BMC Bioinformatics",
"issn": "14712105",
"sjrValue": 1.1,
"coverImageUrl": "https://s3.amazonaws.com/thirdiron-assets/images/covers/1471-2105.png",
"browzineEnabled": true,
"browzineWebLink": "https://browzine.com/libraries/222/journals/74?utm_source=api_29"
}
]
}
Importantly are these two elements for implementation consideration:
Property | Type | Description | Optional |
|---|---|---|---|
sjrValue | number | The SJR (Scimago Journal Rank) value of the journal. Utilize to display this value in your interface to show the general prestige of this journal. | No |
coverImageUrl | URL | The link to the cover image. Use this element to feature a representative cover image of the title in your interface. | No |
More questions? We are here to help!
Please drop us a line at support@thirdiron.com to start the conversation and thanks for your interest in LibKey!