Institutional Repositories are systems for collecting, preserving, disseminating and promoting the intellectual output of an institution. One of the most common objectives for institutional repositories is to promote the organization's research and teaching activities.
A major challenge for the managers of IR systems is making sure that all of the institute's research output is captured, up-to-date, accompanied with the right metadata and made available in line with Publisher Policies.
With the ScienceDirect APIs Elsevier aims to support institutional repositories with the following:
Repository objectives & use cases | How this objective can be addressed using Elsevier ScienceDirect APIs | |
---|---|---|
Ensure your institutional repository reports on all articles affiliated authors published with Elsevier. | Find articles your authors published in Elsevier journals and books and download structured metadata (including abstracts), using the Metadata Retrieval API. | |
Ensure locally hosted full-text (green OA) accepted manuscripts of Elsevier articles are made available in line with publisher's hosting & posting policies, with minimum hassle. | Responses of the Hosting Permissions API include the embargo end date, the date by which an AM may be made publicly available. | |
Ensure repository users are linked to the best available version. | Use an article identifier (DOI or PII) to check if the user has access on ScienceDirect based on their IP. If so, link the user to the full text of the article on ScienceDirect. If not, show links to locally hosted earlier versions and the ScienceDirect article page (for remote access or other access options). |
Elsevier RESTful APIs provide access to ScienceDirect data to allow developers working on IR systems to write programs that automatically extract data from ScienceDirect periodically, and add that data to their systems. The ScienceDirect data that is available for use in IRs via APIs is subject to the Elsevier content use policies.
Getting access to the ScienceDirect APIs for institutional repositories takes few simple steps:
Register for an API key here.
Register for the institutional repository program here and submit your API key: Institutional Repository - Learn & Support - ScienceDirect | Elsevier. The Elsevier integration support team will add the ScienceDirect IR settings to your API key, and confirm back. If your institution already has a Scopus API key, you can submit this API key to have the settings for the SD IR services added.
Develop your IR software. Detailed technical documentation on the ScienceDirect API integration is on this page.
Note: API keys used in this document are example API keys. Please make sure to replace them with your API key.
Important Note: We recommend Repositories from institutions that subscribe to Scopus to use the Scopus Search API to retrieve cross-publisher metadata. For more information please see Scopus IR/CRIS/VIVO How To Guide.
https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29&httpAccept=application/xml&apiKey=[my_api_key]where
aff
is the name of the affiliation field, followed by a name of the institution enclosed in parenthesis;httpAccept=
specifies the desired response format;apiKey=
specifies your registered API key.https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%20MIT%29%20or%20aff%28broad%20institute%20Harvard%29%20or%20aff%28broad%20institute%29&httpAccept=application/xml&apiKey=[my_api_key]The number of search results that can be retrieved via a single API request is anywhere from 25 to 200, depending on institutional access rights and API service levels. For most institutions this is sufficient to retrieve articles published in the last month, which appears a suitable frequency to keep the repository updated. Institutions that would like to retrieve more results, for example because they would like to download metadata for articles published over a longer period, we suggest to narrow down the result set by using publication year restriction. For example: the repository aims to host articles published after year 2000. In this case, the API requests for initial repository population should contain
pub-date
year restriction for each year such as 2000, 2002, 2003, ..., 2014, 2015:
https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29%20and%20pub-date%20is%202014&httpAccept=application/xml&apiKey=[my_api_key]
pub-date
can utilize the date format YYYYMMDD when using the operators BEF
(before) and AFT
(after), which can be used to denote a publication date prior to or after the specified date(s) such as pub-date AFT 20140630 AND pub-date BEF 20141001 for all articles in the third quarter of 2014.
https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29%20and%20pub-date%20AFT%2020140630%20AND%20pub-date%20BEF%2020141001&httpAccept=application/xml&apiKey=[my_api_key]
view=COMPLETE
on the API request as shown below:
https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29%20and%20pub-date%20is%202014&view=COMPLETE&httpAccept=application/xml&apiKey=[my_api_key]
<opensearch:totalResults>
counts. To programmatically iterate over search results
set please use URL in href
element of the <link ref="next"
provided in the Article Metadata API response. Here is example:
<opensearch:totalResults>255</opensearch:totalResults> <opensearch:startIndex>0</opensearch:startIndex> <opensearch:itemsPerPage>25</opensearch:itemsPerPage> <opensearch:Query role="request" searchTerms="aff(broad institute) and pub-date is 2014" startPage="0"/> <link ref="self" href="https://api.elsevier.com/content/metadata/article?start=0&count=25&query=aff%28broad+institute%29+and+pub-date+is+2014&view=COMPLETE&httpAccept=application/xml" type="application/xml"/> <link ref="first" href="https://api.elsevier.com/content/metadata/article?start=0&count=25&query=aff%28broad+institute%29+and+pub-date+is+2014&view=COMPLETE&httpAccept=application/xml" type="application/xml"/> <link ref="next" href="https://api.elsevier.com/content/metadata/article?start=25&count=25&query=aff%28broad+institute%29+and+pub-date+is+2014&view=COMPLETE&httpAccept=application/xml" type="application/xml"/> <link ref="last" href="https://api.elsevier.com/content/metadata/article?start=230&count=25&query=aff%28broad+institute%29+and+pub-date+is+2014&view=COMPLETE&httpAccept=application/xml" type="application/xml"/>
https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29%20and%20pub-date%20aft%202014&view=COMPLETE&httpAccept=application/xml&apiKey=[my_api_key]
We suggest storing metadata about Elsevier article, including article identifier called PII and a link to ScienceDirect article (returned in the ScienceDirect Article Metadata API response), when populating institutional repository. PII will be used to call Article Entitlement Retrieval API as described later in this document.
Example or PII and ScienceDirect link returned in ScienceDirect Article Metadata API response:
<pii>S0049-3848(14)00284-9</pii>
<link ref="self" href="http://api.elsevier.com/content/article/pii/S0049384814002849"/>
Field Name | ScienceDirect API response element |
---|---|
Creator | <dc:creator> |
Date | <prism:coverDate> |
Description | <dc:description> |
Identifier | <dc:identifier> |
Rights | <prism:copyright> |
Source | <prism:publicationName> |
Title | <dc:title> |
Type | <pubType> |
Important Note: ScienceDirect Article Entitlements API accepts the following article identifiers: PII, DOI, EID, scopus_id and pubmed_id as described in corresponding API specification. Institutions that subscribe to Scopus may use the Scopus Search API to retrieve cross-publisher metadata that includes article identifiers as described in Scopus IR/CRIS/VIVO How To Guide. The repository may use any authoritative source of the article metadata to obtain one of the article identifiers accepted by the ScienceDirect Article Entitlements API.
<pii>S0049-3848(14)00284-9</pii>
http://api.elsevier.com/content/article/entitlement/pii/S0049-3848(14)00284-9?apiKey=[my_api_key]
<entitled>true</entitled>
or
<entitled>open_access</entitled>
. If the user does not have access, the API response will contain <entitled>false</entitled>
.
If the article was not found, the HTTP status code will be 404, <entitled>
element will not be present in the response payload while <entry status="not_found">
will be returned.
http://api.elsevier.com/content/article/entitlement/pii/S0049-3848(14)00284-9,S0955286315000716,S2211419X14001062?apiKey=[my_api_key]
Important Note: The Article Entitlement Retrieval API should be called from the user's browser by integrating it directly with the IR's web page via JavaScript. In order to comply with cross-origin security policy, IR domains must be added to the API key configuration to enable W3C CORS support. After creating an API key, please select your API key to add or modify CORS domains. Additional information regarding CORS and Elsevier APIs can be found here.
http://api.elsevier.com/content/article/hostingpermission/pii/S0955286315000716?apiKey=[my_api_key]&httpAccept=text/xml
<hosting-permission-response xmlns="http://www.elsevier.com/xml/svapi/hostingpermissions/dtd" xmlns:xocs="http://www.elsevier.com/xml/xocs/dtd" xmlns:tb="http://www.elsevier.com/xml/common/table/dtd" xmlns:sb="http://www.elsevier.com/xml/common/struct-bib/dtd" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:ja="http://www.elsevier.com/xml/ja/dtd" xmlns:ce="http://www.elsevier.com/xml/common/dtd" xmlns:cals="http://www.elsevier.com/xml/common/cals/dtd" xmlns:bk="http://www.elsevier.com/xml/bk/dtd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:prism="http://prismstandard.org/namespaces/basic/2.0/" xmlns:jav="http://www.niso.org/schemas/jav/1.0/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:ali="http://www.niso.org/schemas/ali/1.0/"> <document-hosting-permission status="found"> <dc:identifier>http://dx.doi.org/10.1016/j.jnutbio.2015.02.010</dc:identifier> <prism:url>http://api.elsevier.com/content/article/pii/S0955286315000716</prism:url> <prism:doi>10.1016/j.jnutbio.2015.02.010</prism:doi> <pii>S0955-2863(15)00071-6</pii> <pii-norm>S0955286315000716</pii-norm> <link rel="scidir" href="http://www.sciencedirect.com/science/article/pii/S0955286315000716"/> <timestamp>2015-10-23T13:43:14.623752-04:00</timestamp> <hosting-platform type="institutional_repository"> <document-version> <jav:journal_article_version>AM</jav:journal_article_version> <hosting-allowed audience="Internal"> <allowed-audience> <prism:url>http://api.elsevier.com/affiliation/affiliation_id/115791654</prism:url> <dc:identifier>AFFILIATION_ID:115791654</dc:identifier> <affiliation-name>Molecular Infectious Disease Research Centre</affiliation-name> </allowed-audience> <allowed-audience> <prism:url>http://api.elsevier.com/affiliation/affiliation_id/60020351</prism:url> <dc:identifier>AFFILIATION_ID:60020351</dc:identifier> <affiliation-name>Chang Gung University</affiliation-name> </allowed-audience> <allowed-audience> <prism:url>http://api.elsevier.com/affiliation/affiliation_id/60003934</prism:url> <dc:identifier>AFFILIATION_ID:60003934</dc:identifier> <affiliation-name>Chang Gung Children's Hospital</affiliation-name> </allowed-audience> <allowed-audience> <prism:url>http://api.elsevier.com/affiliation/affiliation_id/60031913</prism:url> <dc:identifier>AFFILIATION_ID:60031913</dc:identifier> <affiliation-name>Chang Gung Memorial Hospital</affiliation-name> </allowed-audience> </hosting-allowed> <hosting-allowed start_date="2016-06-10" audience="Public"/> <required-license>http://creativecommons.org/licenses/by-nc-nd/4.0/</required-license> </document-version> <document-version> <jav:journal_article_version>VoR</jav:journal_article_version> <hosting-not-allowed/> </document-version> </hosting-platform> </document-hosting-permission> </hosting-permission-response>
<?xml version="1.0" encoding="UTF-8"?> <hosting-permission-response> <document-hosting-permission status="found"> ... <hosting-platform type="institutional_repository"> <document-version> <jav:journal_article_version>AM</jav:journal_article_version> <hosting-.../>
<hosting-not-allowed/>
element.<hosting-permissions-forthcoming/>
element.<hosting-allowed start_date="2015-06-10" audience="Public"/>
.Article Hosting Permissions API response example | What to be displayed to an internal IR user (a user affiliated with institution) |
---|---|
<hosting-not-allowed/> | IR can show hosted accepted manuscript (if available) and a VoR link to ScienceDirect |
<hosting-permissions-forthcoming/> | IR can show hosted accepted manuscript (if available) and a VoR link to ScienceDirect |
Start date is in the past <hosting-allowed start_date="2015-06-10" audience="Public"/> |
IR can show hosted accepted manuscript (if available) and a VoR link to ScienceDirect |
Start date is in the future <hosting-allowed start_date="2017-06-10" audience="Public"/> |
IR can show hosted accepted manuscript (if available) and a VoR link to ScienceDirect |
Article Hosting Permissions API response example | What to be displayed to a public IR user (a user not affiliated with institution) |
---|---|
<hosting-not-allowed/> | IR can show article metadata and a VoR link to ScienceDirect |
<hosting-permissions-forthcoming/> | IR can show article metadata and a VoR link to ScienceDirect |
Start date is in the past <hosting-allowed start_date="2015-06-10" audience="Public"/> |
IR can show hosted accepted manuscript (if available) and a VoR link to ScienceDirect or DOI link |
Start date is in the future <hosting-allowed start_date="2017-06-10" audience="Public"/> |
IR can show article metadata and a VoR link to ScienceDirect or DOI links |
Depending on the response from the Article Entitlement API and Article Hosting Permissions API the repository should dynamically decide which links should be displayed to a user. To assist with this task please refer to the table below.
Article Entitlement API response | Links to be used | Suggested link text | Suggested access information for user |
---|---|---|---|
User has access to full text <entitled>true</entitled> |
VoR link to a full-text article on ScienceDirect | Version of Record | (you have access) |
<entitled>open_access</entitled> | VoR link to a full-text article on ScienceDirect | Version of Record | (open access) |
User does not have access to full text <entitled>false</entitled> |
Link to IR hosted accepted manuscript (if available) based on the rules specified in Table 1 and Table 2 using Article Hosting Permissions API response | Accepted Manuscript | (you have access) |
and | |||
VoR link | Version of Record | (check access) | |
An error occurred or document not found HTTP/1.1 404 Not Found <entry status="not_found"> |
Link to IR hosted manuscript (if available) | Accepted Manuscript | (you have access) |
and | |||
VoR link | Version of Record | (Check access) |
The ScienceDirect Article Metadata API response will contain a link to an article on ScienceDirect platform for each search results entry. Here is example:
<link ref="scidir" href="http://www.sciencedirect.com/science/article/pii/S0049384814002849"/>
The URL "http://www.sciencedirect.com/science/article/pii/S0049384814002849" from the href element in <link ref="scidir" href= ... >
is the actual link to the article on ScienceDirect.
http://www.sciencedirect.com/science/article/pii/[PII]where [PII] should be replaced with an actual article PII (such as S0049-3848(14)00284-9 or S0049384814002849) returned in ScienceDirect Article Metadata API response and stored along with article metadata as described in section 1 above.
Please note that all Elsevier API requests can be implemented using Javascript. In order to comply with cross-origin security policy, IR domains must be added to the API key configuration to enable W3C CORS support. After creating an API key, please select your API key to add or modify CORS domains. Additional information regarding CORS and Elsevier APIs can be found here.