Skip to content

WileyIntelligentSolutions/wosjournals-py-client

BranchesTags
 
 

Repository files navigation

Web of Science Journals API Python client

This API provides journal-level metadata and metrics for all journals in the Journal Citation Reports™ covered in the Web of Science Core Collection, including the Journal Impact Factor™ and other new metrics. Integrate journal data into your internal systems or retrieve journal indicators for bibliometrics studies.

Resources

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. The access requires registration on the Portal and approval from the Clarivate Sales/Product teams to entitle to the API.

Credentials

All requests require authentication with an API Key authentication flow. For more details, check the Guide.

Content

You can learn more about content at Journal Citation Reports™ Product page, or in the documentation.

<a name="search"> Search (query parameter q=)

This API supports free-text search for a journal name, abbreviation, ISSN code, publisher, and Web of Science™ category name (only /categories endpoint). You need to provide a complete and valid ISSN code pattern; otherwise, the API will not look up for ISSN codes.

Boolean operators

Operator Description Example
+ / " " Search by two or more terms in the same field. Blank space is the same as an AND operator. The search retrieves all the records that contain the terms, e.g., /journals?q=matrix biology
/journals?q=nature+group
OR Search by at least one term in the field. The search retrieves all the records that contain one of the terms, e.g., /journals?q=gas OR oil
NOT / - Search by excluding specific terms. The search retrieves all the records that match the query specifics, e.g., /journals?q=genetics -nature

Special symbols

The wildcards ( * ) are allowed in the search that starts with the search query: /journals?q=nano* will search indications that start from nano: for example, Nanotechnology or nanotubes.

Please note: the free text search query (with the parameter q=) should contain at least three symbols.

Filtering

The API supports several filters for Journals and Web of Science™ Categories, narrowing down the initial list of entities or search results.

There are two types of filters:

  • Filter by one or multiple values: edition, categoryCode, jcrYear, jifQuartile
  • Filter by range: jif, jifPercentile

Filter by values

The filter name goes before the equals sign, followed by one or multiple filter values, separated by a semicolon, like categoryCode=RZ;RU. You can combine various filters with or without the search. Filters are separated by an ampersand (&): q=nature&categoryCode=RU;KM&jcrYear=2018

Please note: filter by jcrYear allows only one year value as an input

Filter by range

The API supports range filtering for Journal Impact Factor (jif) or Journal Impact Factor Percentile (jifPercentile) with the following operators:

  • eq (equal): if a Journal Impact Factor (Percentile) is equal to a specific number.
    For example: for jif=eq:5.032 the result will include journals with Journal Impact Factor = 5.032.
    Not combinable with any other operator
  • gt (greater than): if a Journal Impact Factor (Percentile) is greater than a specific number.
    For example: for jif=gt:5 the result will include journals with Journal Impact Factor = 5.001 and higher.
    Combinable with lt and lte operators
  • gte (greater than equal): if a Journal Impact Factor (Percentile) is greater than or equal to a specific number.
    For example: for jif=gte:5 the result will include journals with Journal Impact Factor = 5.000 and higher.
    Combinable with lt and lte operators
  • lt (less than): if a Journal Impact Factor (Percentile) is less than a specific number.
    For example: for jif=lt:5 the result will include journals with Journal Impact Factor = 4.999 and less.
    Combinable with gt and gte operators
  • gt (less than equal): if a Journal Impact Factor (Percentile) is less than a specific number.
    For example: for jif=lte:5 the result will include journals with Journal Impact Factor = 5.000 and less.
    Combinable with gt and gte operators

Use AND to combine two operators, e.g.,jifPercentile=gte:50 AND lte:80 responses with all journals in a percentile range from 50% to 80% (both included).

Pagination

To ensure fast response time, each search or multiple entity calls (such as /journals or /categories/ID/cited/year/YYYY) 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 information in WoS Journals API about the identifier ABC_DEF for the Journals content area. Sorry :(\"
}

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

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

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.0
  • Package version: 1.0.0
  • Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements

Python >= 3.6

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/Clarivate-SAR/wos-journals-client-py.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/Clarivate-SAR/wos-journals-client-py.git)

Then import the package:

import wosjournalsclientpy

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import wosjournalsclientpy

Getting Started

Please follow the installation procedure and then run the following:

import time
import wosjournalsclientpy
from pprint import pprint
from wosjournalsclientpy.api import categories_api
from wosjournalsclientpy.model.inline_response2005 import InlineResponse2005
from wosjournalsclientpy.model.inline_response2006 import InlineResponse2006
from wosjournalsclientpy.model.inline_response2007 import InlineResponse2007
from wosjournalsclientpy.model.inline_response2008 import InlineResponse2008
from wosjournalsclientpy.model.inline_response2009 import InlineResponse2009
# Defining the host is optional and defaults to https://api.clarivate.com/apis/wos-journals/v1
# See configuration.py for a list of all supported configuration parameters.
configuration = wosjournalsclientpy.Configuration(
    host = "https://api.clarivate.com/apis/wos-journals/v1"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: key
configuration.api_key['key'] = 'YOUR_API_KEY'

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['key'] = 'Bearer'


# Enter a context with an instance of the API client
with wosjournalsclientpy.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = categories_api.CategoriesApi(api_client)
    q = "q_example" # str | Free-text search by category name.  Search logic is described in the section [Search](#search). (optional)
edition = "edition_example" # str | Filter by Web of Sceince Citation Index. The following indexes (editions) are presented: - SCIE - Science Citation Index Expanded (ournals across more than 170 disciplines) - SSCI - Social Sciences Citation Index (journals across more than 50 social science disciplines)  Multiple values are allowed, separated by semicolon ( **;** ) (optional)
jcr_year = 1 # int | Filter by Category Citation Report year (from 2003).  Only one value is allowed. (optional)
page = 1 # int | Specifying a page to retrieve (optional) (default to 1)
limit = 10 # int | Number of returned results, ranging from 0 to 50 (optional) (default to 10)

    try:
        # Search and filter across the journal categories
        api_response = api_instance.categories_get(q=q, edition=edition, jcr_year=jcr_year, page=page, limit=limit)
        pprint(api_response)
    except wosjournalsclientpy.ApiException as e:
        print("Exception when calling CategoriesApi->categories_get: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://api.clarivate.com/apis/wos-journals/v1

Class Method HTTP request Description
CategoriesApi categories_get GET /categories Search and filter across the journal categories
CategoriesApi categories_id_cited_year_year_get GET /categories/{id}/cited/year/{year} Get journals that cite all journals in the category for the JCR year
CategoriesApi categories_id_citing_year_year_get GET /categories/{id}/citing/year/{year} Get journals that were cited by all journals from the category for the JCR year
CategoriesApi categories_id_get GET /categories/{id} Get a category
CategoriesApi categories_id_reports_year_year_get GET /categories/{id}/reports/year/{year} Get category metrics for a year
JournalsApi journals_get GET /journals Search and filter across JCR Journals
JournalsApi journals_id_cited_year_year_get GET /journals/{id}/cited/year/{year} Get journals that cite the journal for the JCR year
JournalsApi journals_id_citing_year_year_get GET /journals/{id}/citing/year/{year} Get journals that were cited by the journal for the JCR year
JournalsApi journals_id_get GET /journals/{id} Get journal by id
JournalsApi journals_id_reports_year_year_get GET /journals/{id}/reports/year/{year} Get journal metrics for a year

Documentation For Models

Documentation For Authorization

key

  • Type: API key
  • API key parameter name: X-ApiKey
  • Location: HTTP header

Author

Notes for Large OpenAPI documents

If the OpenAPI document is large, imports in wosjournalsclientpy.apis and wosjournalsclientpy.models may fail with a RecursionError indicating the maximum recursion limit has been exceeded. In that case, there are a couple of solutions:

Solution 1: Use specific imports for apis and models like:

  • from wosjournalsclientpy.api.default_api import DefaultApi
  • from wosjournalsclientpy.model.pet import Pet

Solution 2: Before importing the package, adjust the maximum recursion limit as shown below:

import sys
sys.setrecursionlimit(1500)
import wosjournalsclientpy
from wosjournalsclientpy.apis import *
from wosjournalsclientpy.models import *

About

Web of Science Journals API Python Client

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Python 99.9%
  • Shell 0.1%