wos-api-starter-client

Web of Science™ Starter API

API version: 1.0.0
- Build date: 2022-04-06T14:38:20.941+02:00[Europe/Paris]

The Web of Science™ Starter API provides basic metadata and search functionality for Web of Science™ Documents and Journals. Based on your subscription, this API can return times cited of documents.

Resouces

This API follows the REST approach to disclose resources in URL format. Only the GET method is currently available to perform requests over HTTP.

The API is available on the Clarivate Developer Portal. You can find more details about the subscription and the Plans.

Content

You can learn more about content at Web of Science™ Product Page or in the Web of Science™ Help. The following attributes are available from in the API.

UID (Unique Identifier)
Title
Issue
Pages
DOI
Volume
Times Cited
ISSN/eISSN
ISBN
PubMed ID
Source
Web of Science URL
Citing Articles Web of Science URL
Publication Date
Authors
Author Keywords
Document Type
Cited References Web of Science URL
ResearcherID
Book DOI
Related Records Web of Science URL
Journal Citations Reports URL

Credentials

All requests require authentication with an API Key authentication flow. For more details, check the [Guide][https://developer.clarivate.com/help/api-access#key_access].

Search and field tags for Web of Science documents

Web of Science™ offers advanced search query builder. This API does not support all field tags for documents. Web of Science API Expanded offers all available field tags. The following table lists the field tags that are supported by this API.

Field Tag	Description
TI	Title of document
IS	ISSN or ISBN
SO	Source title - The result contains all source titles within product database (for example, journal titles and/or book titles if the product includes books)
VL	Volume
PG	Page
CS	Issue
PY	Year Published
AU	Author
AI	Author Identifier
UT	Accession Number
DO	DOI
DT	Document Type
PMID	PubMed ID
OG	Search for preferred organization names and/or their name variants from the Preferred Organization Index. A search on a preferred organization name returns all records that contain the preferred name and all records that contain its name variants. A search on a name variant returns all records that contain the variant. For example, Cornell Law Sch returns all records that contain Cornell Law Sch in the Addresses field. When searching for organization names that contain a Boolean (AND, NOT, NEAR, and SAME), always enclose the word in quotation marks ( " " ). For example: - OG=(Japan Science "and" Technology Agency (JST)) - OG=("Near" East Univ) - OG=("OR" Hlth Sci Univ)
TS	Searches for topic terms in the following fields within a document: - Title - Abstract - Author keywords - Keywords Plus

Pagination

To ensure fast response time, each search or multiple entity calls (such as /documents) retrieve only a certain number of hits/records.

There are two optional request parameters to browse along with the result: limit and page.

limit: Number of returned results, ranging from 0 to 50 (default 10)
page: Specifying a page to retrieve (default 1)

Moreover, this information is shown in the response body, in the tag metadata:

\"metadata\": {
  \"total\": 91,
  \"page\": 1,
  \"limit\": 10
}

Errors

The WoS Journals API uses conventional HTTP success or failure status codes. For errors, some extra information is included to indicate what went wrong in the JSON response. The list of HTTP codes is listed below.

Code	Title	Description
400	Bad request	Request syntax error
401	Unauthorized	The API key is invalid or missed
404	Not found	The resource is not found
405	Method not allowed	Method other than GET is not allowed
50X	Server errors	Technical error with servers
Each error response (except `401 Unauthorized` error) contains the code of the error, the title of the error and detailed description of the error: a misprint in an endpoint, wrong URL parameter, etc. The example of the error message is shown below:

  \"error\": {
    \"status\": 404,
    \"title\": \"Resource couldn't be found\",
    \"details\": \"There is no record found in the Web of Science database. Please check your query.\"
  }

For the 401 Unauthorized error the response body is a little bit different:

{
  \"error_description\": \"The access token is missing\",
  \"error\": \"invalid_request\"
}



*Automatically generated by the [OpenAPI Generator](https://openapi-generator.tech)*


## Requirements

Building the API client library requires:
1. Java 1.7+
2. Maven (3.8.3+)/Gradle (7.2+)

## Installation

To install the API client library to your local Maven repository, simply execute:

```shell
mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>com.clarivate.wos</groupId>
  <artifactId>wos-api-starter-client</artifactId>
  <version>1.0.0</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

  repositories {
    mavenCentral()     // Needed if the 'wos-api-starter-client' jar has been published to maven central.
    mavenLocal()       // Needed if the 'wos-api-starter-client' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "com.clarivate.wos:wos-api-starter-client:1.0.0"
  }

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

target/wos-api-starter-client-1.0.0.jar
target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

// Import classes:
import com.clarivate.wos.wos_api_starter_client.invoker.ApiClient;
import com.clarivate.wos.wos_api_starter_client.invoker.ApiException;
import com.clarivate.wos.wos_api_starter_client.invoker.Configuration;
import com.clarivate.wos.wos_api_starter_client.invoker.models.*;
import com.clarivate.wos.wos_api_starter_client.DocumentsApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://api.clarivate.com/apis/wos-starter");

    DocumentsApi apiInstance = new DocumentsApi(defaultClient);
    String q = "PY=2020"; // String | Web of Science advanced [advanced search query builder](https://webofscience.help.clarivate.com/en-us/Content/advanced-search.html). The supported field tags are listed in description.
    String db = "BCI"; // String | Web of Science Database abbreviation * WOS - Web of Science Core collection * BIOABS - Biological Abstracts * BCI - BIOSIS Citation Index * BIOSIS - BIOSIS Previews * CCC - Current Contents Connect * DIIDW - Derwent Innovations Index * DRCI - Data Citation Index * MEDLINE - MEDLINE The U.S. National Library of Medicine® (NLM®) premier life sciences database. * ZOOREC - Zoological Records * WOK - All databases 
    Integer limit = 10; // Integer | set the limit of records on the page (1-50)
    Integer page = 1; // Integer | set the result page
    String sortField = "sortField_example"; // String | Order by field(s). Field name and order by clause separated by '+', use A for ASC and D for DESC, ex: PY+D. Multiple values are separated by comma. Supported fields:  * **LD** - Load Date * **PY** - Publication Year * **RS** - Relevance * **TS** - Times Cited 
    try {
      DocumentsList result = apiInstance.documentsGet(q, db, limit, page, sortField);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling DocumentsApi#documentsGet");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Documentation for API Endpoints

All URIs are relative to http://api.clarivate.com/apis/wos-starter

Class	Method	HTTP request	Description
DocumentsApi	documentsGet	GET /documents	Query Web of Science documents
DocumentsApi	documentsUidGet	GET /documents/{uid}	Get Web of Science document by Accesssion Number (UID)
JournalsApi	journalsGet	GET /journals	Query Journals by ISSN
JournalsApi	journalsIdGet	GET /journals/{id}	Get Journal by ID

Documentation for Models

Documentation for Authorization

All endpoints do not require authorization. Authentication schemes defined for the API:

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

clarivate/wosstarter-java-client