Enhance your web application with Scopus content.

Return button

Scopus Document Search API Documentation

Download the Document Search API Documentation (PDF file, 36 KB)


Introduction

The Scopus Application Programmer Interface (API) for ScopusTM allows you to present Scopus search results through your own product's user interface via software that you develop.

Prerequisite Knowledge

In order to use this guide, you must be familiar with the following:

Back to top


Terms & Conditions

Click one of the following links to review terms and conditions for using Scopus API.

Back to top


Using Scopus API

Complete the following steps to use Scopus API:

  1. Register at Scopus API Developer Registration. See Registering for a Developer Key for more information.

    Note Once you register, you will receive a Developer Key so you may begin creating your webpage.

  2. Contact the Scopus Product organization for details about obtaining access to the Scopus API.

  3. Create your webpage using the JavaScript example listed within this API.

  4. Test your integrator software in your test environment.

  5. Arrange for hosting your webpage.

  6. Test your webpage by conducting a search. The Scopus API will conduct your Scopus search.

Back to top


Registering for a Developer Key

Prior to creating a web page which will use the Scopus API, you must register for a developer's key.

Complete the following steps to register for your developer key:

  1. If you have not already registered, go to http://searchapi.scopus.com and create a Scopus account.

  2. Click Registration to open the Scopus API Registration page.

  3. From the Scopus API Registration page, complete the following fields:
    • Name

    • E-mail address

    • Website url (the website URL where you will use your Scopus Search results)

    • Password

    • Confirm Password

  4. Read the Scopus Registered User Agreement and click the check-box to indicate you accept the agreement.

  5. Click Submit to complete your registration for using the Scopus API.

Note Once you have registered successfully, you can create additional Developer IDs.

Back to top


JavaScript Code Example

The following example is basic html page with JavaScript (highlighted in red). Highlight and copy red portions of text into your html page.

See JavaScript Element Definitions for definitions of JavaScript elements

Basic JavaScript

<html>
     <head>
         <title>Scapi Test/Demo Tool</title>
                <!-- SECTION 1 : Initial configuration -->
                    <link REL="stylesheet" TYPE="text/css" href="http://searchapi.scopus.com/stylesheets/css_scapi_list_hilight.css"/>
                        <script type="text/javascript" src="http://searchapi.scopus.com/scripts/scapi.jsp"></script>
                        <script type="text/javascript">
                            <!-- SECTION 2 : Call back -->
                               callback = function(){ document.scapiForm.searchButton.disabled = false; }
                            <!-- SECTION 3 : Running Search -->
                               runSearch = function(){
                               document.scapiForm.searchButton.disabled = true;
                               var varSearchObj = new searchObj();
                               varSearchObj.setSearch(document.scapiForm.searchString.value);
                               scapi.search(varSearchObj);
                               }
                        </script>
                <!-- SECTION 4 : Setting defaults -->
                        <script type="text/javascript">
                            scapi.setDeveloperID("--INSERT YOUR DEVELOPER ID HERE--");
                            scapi.setCallback(callback);
                        </script>
     </head>
<!-- SECTION 5 : Rendering page -->
     <body>
         <h2>Search Form:</h2>
                  <form name="scapiForm" onsubmit="return false">
                      <input type="text" name="searchString"/>
                      <button onClick="runSearch()" name="searchButton"/>SEARCH</button>
                  </form>
         <h2>Returned SCAPI Content:</h2>
                  <div id="scapi">
                      None.
                  </div>
     </body>
</html>

Back to top


JavaScript Element Definitions

Below are the methods that are used in the JavaScript example. This is the main JavaScript "class" you will use to make calls to the Scopus API. The JavaScript creates a global variable which the Scopus API will use to access these methods (i.e. scapi.areSearchResultsValid()).

Main JavaScript Methods

Element Definition
areSearchResultsValid() Returns true of false depending on if the search competed successfully.
getLastSearchRequest() Returns the searchObj for the previous search. Will return null if no previous search has occurred.
selectRenderer(renderer) Select which of the Elsevier supplied renderers to use. Currently the only supported renderer value is "list". Any other value will not change from the default renderer.
setDeveloperID(DeveloperID) Sets developerID to be used for all searches. This must be run for searches to work, and it must be a valid developerID.
setErrorCallback(JavaScriptFunction) (Optional) Sets the name of the method to be called when an error occurs during a search.
setRenderer(renderer) Overrides the default renderer with a custom-written, user-supplied renderer. The renderer will have certain methods that must be implemented (i.e. an interface) to work properly. <div id="fillInData"> goes with <scapi.setRenderLocation(“fillInData”);> .
setRenderLocation(divtag) Sets the position to be overwritten by the renderer when rendering content. This should be the string value of the div tag to be replaced.
setCallback(JavaScriptFunction) (Optional) Sets the method to call when the search processing is complete.
runSearch(searchObj) Runs a search string and then calls the callback method without calling the renderer; allows access to the conditional methods without using the default renderer.
search(searchObj) Runs a search using the backend and displays the results via the renderer. A call is then made to the callback method to return control to your code.

Conditional Methods

The following methods will not work correctly unless AreSearchResultsValid() returns true. This occurs after a search is ran.

Element Definition
getSearchResults() Returns the search results object.
renderDocument(position) Renders a single document at the specified position in the HTML and displays it via the renderer.
renderField(position, field) Renders a single field of a document at the specified position in the HTML and displays it via the renderer.
getField(position, field) Returns a single field of a document at the specified position.
getTotalHits() Returns the total number of hits in the search.
getNumResults() Returns the total number of results returned by the search.
getPossition() Returns the offset.
getSearchRequest() Returns the last submitted search request object.

searchObj class

You will have to create your own instance of this object (i.e. new searchObj()).

Element Definition
setFields(fields) Sets the fields to be returned. This is a comma separated string with no spaces. The valid values are:
  • Registered users: title, doctype, citedbycount, inwardurl, sourcetitle, issn, vol, issue, page, pubdate, eid, scp, doi, firstauth, authlist, affiliations, and abstract.
  • Non-registered users: title, doctype, citedbycount, inwardurl, sourcetitle, issn, vol, issue, page, pubdate, eid, scp, doi, affiliations, and firstauth.
setNumResults(numResults) Sets the number of results to return. The valid values are: 1-20 for non-registered users and 1-2000 for registered users.
setOffset(offset) Sets how may documents will be skipped before displaying results. If the offset is 20, then results 21 and beyond will display.

Registered users may view up to 2,000 documents. An offset of 10 will allow a user to view documents 11 through 2,000 (if that many are available in the results).

Non-registered users may only view 20 documents. An offset of 10 will allow the user to view documents 11 through 20.

setSearch(search) Sets the search string. Any search string that can be typed into the advanced search form will work.
setSort(sort) Sets the field to sort documents by. The valid values are: Date (publishing date), Relevancy, Authors, SourceTitle, CitedByCount, and LoadDate (date loaded to Scopus).
setSortDirection(sortDirection) Sets the sort direction. The valid values are: Ascending and Descending.
getContent() Returns the currently set content.
getFields() Returns the currently set fields (comma separated strings).
getNumResults() Returns the currently set number of results.
getOffset() Returns the currently set offset.
getSearch() Returns the currently set search.
getSort() Returns the currently set sort.
getSortDirection() Returns the currently set sort direction.

To Override the Renderer

If you want to override the renderer with your own code, you must implement the following functions for it to work correctly. The code is in JavaScript to avoid confusion and must be exact.

Element Definition
this.setRenderLocation = function(idName){ Sets a new render location overriding the previous one.
this.renderErrors = function(errors){ Renders any errors.
this.renderWarnings = function(warnings){ Renders any warnings.
this.renderResults = function(response){ Renders the response
this.renderField = function(response, position, field){ Renders a specific field.

Back to top