Skip to main content

Elsevier Developer Portal

Using ScienceDirect APIs for Institutional Repositories

Introduction

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

Process for getting access to ScienceDirect APIs

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:

  1. Register for an API key here.

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

  3. Develop your IR software. Detailed technical documentation on the ScienceDirect API integration is on this page.

Instructions for using APIs for the supported use cases


Note: API keys used in this document are example API keys. Please make sure to replace them with your API key.


Identifying publications affiliated with your institution


Initial repository population with article metadata


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.


The ScienceDirect Article Metadata API (interactive documentation is available here, detailed interface documentation is available here) can be leveraged to identify articles that are written by authors that are affiliated with your institution. In order to do that you can construct a field restricted search by affiliation as follows:

https://api.elsevier.com/content/metadata/article?query=aff%28broad%20institute%29&httpAccept=application/xml&apiKey=[my_api_key]
where If the institution has changed names over the years, the API request can be constructed to accommodate name variants in the affiliation search as follows:

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]

Note that date restrictions can also be made for explicit dates, either matching or within a particular range. For example, the comparsions for 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]

Note that these operators BEF and AFT are only applicable for specific fields, such as dates.
If you are planning to make use of article abstracts, you will need to specify 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]

Please check if search returned non-zero results by examining <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"/>

Update repository with newly published article metadata


Upon completing initial repository population, the update process can use the following API request including a search for pub-date after the last year used for initial repository population:

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]

Metadata


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"/>

Please find metadata field mappings below:
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>

Determine whether user has access to a full-text article


To determine the best available article version to be presented to the user we need to find out whether the user has access to the full-text version of the article on ScienceDirect using Article Entitlements API.

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.


Here is an example of the PII returned by ScienceDirect Article Metadata API for an article: <pii>S0049-3848(14)00284-9</pii>

The PII should be used to determine the end user's article access using Article Entitlement Retrieval API as shown below, the API request must be made from the user's browser (client side):

http://api.elsevier.com/content/article/entitlement/pii/S0049-3848(14)00284-9?apiKey=[my_api_key]

If the user has access to the full text of the article, the Article Entitlement Retrieval API response will contain <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.

It is possible to determine the user's access to multiple documents using a list of document identifiers as shown in example below:

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.


Determine compliance of locally-hosted accepted manuscripts with respect to embargo dates


To determine embargo dates, the Article Hosting Permissions API is used. The article PII is used to determine hosting permissions status via Article Hosting Permissions API as shown in examples below, the Article Hosting Permissions API is used. The article PII is used to determine hosting permissions status via Article Hosting Permissions API as shown in examples below.

Example Article Hosting Permissions API request:

http://api.elsevier.com/content/article/hostingpermission/pii/S0955286315000716?apiKey=[my_api_key]&httpAccept=text/xml

Example Article Hosting Permissions API response:

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

The structure of the API response for the embargo date is as follows:

<?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-.../>

There are 3 possible Article Hosting Permissions API responses:
  1. Hosting of the AM version is not permitted as indicated by <hosting-not-allowed/> element.
  2. Embargo end date is not yet available as indicated by <hosting-permissions-forthcoming/> element.
  3. Embargo end date is indicated in the API response with an actual starte_date element. For example: <hosting-allowed start_date="2015-06-10" audience="Public"/> .

Depending on the Article Hosting Permissions API response, the following rules are used to dynamically determine whether AM version of the article can be presented to various audience types:

Table 1.
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

Table 2.
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

Ensure repository users are linked to the best available article version


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.

Table 3.
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)

VoR link to www.sciencedirect.com

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.

Alternatively, VoR links can be constructed as follows:

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.