The Web of Science API Expanded provides rich bibliographic searching, citation tracking (citing articles and references), related records discovery, and citation reporting with h-index and bibliometric statistics. Requires a paid subscription.
openapi: 3.0.3
info:
title: Web of Science API Expanded
description: >-
The Web of Science API Expanded provides rich searching across the Web of
Science based on your subscription to retrieve item-level metadata,
including times-cited counts and contributor addresses and affiliations.
It supports advanced search, citation analysis, related records discovery,
reference retrieval, and bibliometric reporting with both JSON and XML
output formats.
version: 1.0.0
contact:
name: Clarivate Developer Support
url: https://developer.clarivate.com/support
license:
name: Clarivate Terms of Use
url: https://clarivate.com/legal/terms-conditions/
servers:
- url: https://api.clarivate.com/api/wos
description: Web of Science API Expanded
security:
- ApiKeyAuth: []
paths:
/:
get:
summary: Web of Science Expanded Search Documents via GET
description: >-
Submit search queries to retrieve Web of Science document metadata.
Supports the Web of Science Advanced Search Query syntax with field
tags, boolean operators, and wildcard characters. Returns a query ID
and initial results page for subsequent pagination.
operationId: searchDocumentsGet
tags:
- search
x-microcks-operation:
delay: 100
parameters:
- name: databaseId
in: query
required: true
description: Database to search (e.g., WOS for Web of Science Core Collection).
schema:
type: string
default: WOS
enum:
- WOS
- BIOABS
- BCI
- CCC
- DIIDW
- MEDLINE
- ZOOREC
- name: usrQuery
in: query
required: true
description: >-
Advanced search query string using Web of Science query syntax.
Field tags include TS (topic), AU (author), TI (title), SO
(source), DO (DOI), OG (organization), etc.
schema:
type: string
example: TS=machine learning AND PY=2024
- name: count
in: query
required: false
description: Number of records to return (1-100).
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: lang
in: query
required: false
description: Language of the results (default en).
schema:
type: string
default: en
- name: editions
in: query
required: false
description: Comma-separated list of WOS database editions to search.
schema:
type: string
- name: publishTimeSpan
in: query
required: false
description: >-
Publication date range filter in format begin=YYYY-MM-DD&end=YYYY-MM-DD.
schema:
type: string
- name: sortField
in: query
required: false
description: Field and direction for sorting results.
schema:
type: string
enum:
- LD+D
- PY+D
- TC+D
- RS+D
- LD+A
- PY+A
- name: loadRecord
in: query
required: false
description: Include full record in response.
schema:
type: string
enum:
- Yes
- No
responses:
'200':
description: Successful response with search results and query ID
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request - invalid query
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Web of Science Expanded Search Documents via POST
description: >-
Submit search queries via POST to retrieve Web of Science document
metadata. Equivalent to the GET search endpoint but allows larger
query parameters in the request body.
operationId: searchDocumentsPost
tags:
- search
x-microcks-operation:
delay: 100
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Successful response with search results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/query/{queryId}:
get:
summary: Web of Science Expanded Fetch Query Results
description: >-
Retrieve records from a previously submitted search query using the
query ID returned from the search endpoint. Supports pagination through
large result sets with configurable record counts and sorting.
operationId: getQueryResults
tags:
- search
x-microcks-operation:
delay: 100
parameters:
- name: queryId
in: path
required: true
description: Query identifier returned from the search endpoint.
schema:
type: integer
- name: count
in: query
required: false
description: Number of records to return (1-100).
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: sortField
in: query
required: false
description: Field and direction for sorting results.
schema:
type: string
- name: viewField
in: query
required: false
description: Comma-separated list of fields to include in response.
schema:
type: string
responses:
'200':
description: Successful response with query results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'404':
description: Query not found or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/recordids/{queryId}:
get:
summary: Web of Science Expanded Get Record IDs for Query
description: >-
Retrieve only the unique identifiers for records matching a previously
submitted search query. More efficient than retrieving full records
when only UIDs are needed for deduplication or subsequent lookups.
operationId: getRecordIds
tags:
- search
x-microcks-operation:
delay: 100
parameters:
- name: queryId
in: path
required: true
description: Query identifier returned from the search endpoint.
schema:
type: integer
- name: count
in: query
required: false
description: Number of record IDs to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number for pagination.
schema:
type: integer
minimum: 1
default: 1
responses:
'200':
description: Successful response with array of unique identifiers
content:
application/json:
schema:
$ref: '#/components/schemas/RecordIdsResponse'
'404':
description: Query not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/id/{uniqueId}:
get:
summary: Web of Science Expanded Get Records by Unique ID
description: >-
Retrieve one or more Web of Science records directly by their unique
identifiers. Supports comma-separated lists of UIDs for batch
retrieval. Returns full item-level metadata including addresses and
affiliations.
operationId: getRecordById
tags:
- records
x-microcks-operation:
delay: 100
parameters:
- name: uniqueId
in: path
required: true
description: >-
Single WOS unique identifier or comma-separated list of UIDs
(e.g., WOS:000349044100001,WOS:000349044100002).
schema:
type: string
example: WOS:000349044100001
- name: databaseId
in: query
required: false
description: Database identifier. Defaults to WOS.
schema:
type: string
default: WOS
- name: count
in: query
required: false
description: Number of records to return.
schema:
type: integer
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number.
schema:
type: integer
default: 1
responses:
'200':
description: Successful response with record details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'404':
description: Record not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/citing:
get:
summary: Web of Science Expanded Get Citing Articles
description: >-
Find articles that cite a specific Web of Science document identified
by its unique identifier. Returns citation metadata and times-cited
counts from the Web of Science Core Collection.
operationId: getCitingArticles
tags:
- citations
x-microcks-operation:
delay: 100
parameters:
- name: databaseId
in: query
required: true
description: Database identifier (WOS for Core Collection).
schema:
type: string
default: WOS
- name: uniqueId
in: query
required: true
description: WOS unique identifier of the article to find citing articles for.
schema:
type: string
example: WOS:000349044100001
- name: count
in: query
required: false
description: Number of records to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number.
schema:
type: integer
default: 1
- name: publishTimeSpan
in: query
required: false
description: Publication time span filter.
schema:
type: string
- name: sortField
in: query
required: false
description: Sort field and direction.
schema:
type: string
responses:
'200':
description: Successful response with citing articles
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/references:
get:
summary: Web of Science Expanded Get References for Article
description: >-
Retrieve the reference list cited by a specific Web of Science
document. Returns all cited works including those outside the
Web of Science Core Collection.
operationId: getReferences
tags:
- citations
x-microcks-operation:
delay: 100
parameters:
- name: databaseId
in: query
required: true
description: Database identifier.
schema:
type: string
default: WOS
- name: uniqueId
in: query
required: true
description: WOS unique identifier of the article to get references for.
schema:
type: string
example: WOS:000349044100001
- name: count
in: query
required: false
description: Number of references to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number.
schema:
type: integer
default: 1
responses:
'200':
description: Successful response with reference list
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/related:
get:
summary: Web of Science Expanded Get Related Records
description: >-
Discover records that share cited references with a specified Web of
Science article. Returns the parent record plus related documents
ranked by the number of shared references.
operationId: getRelatedRecords
tags:
- citations
x-microcks-operation:
delay: 100
parameters:
- name: databaseId
in: query
required: true
description: Database identifier.
schema:
type: string
default: WOS
- name: uniqueId
in: query
required: true
description: WOS unique identifier of the article to find related records for.
schema:
type: string
example: WOS:000349044100001
- name: count
in: query
required: false
description: Number of related records to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: firstRecord
in: query
required: false
description: Starting record number.
schema:
type: integer
default: 1
responses:
'200':
description: Successful response with related records
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/citation-report/{queryId}:
get:
summary: Web of Science Expanded Get Citation Report for Query
description: >-
Generate a citation report for a query result set, providing aggregate
citation statistics including total citations, average citations per
item, h-index, and year-by-year citation counts.
operationId: getCitationReport
tags:
- reports
x-microcks-operation:
delay: 100
parameters:
- name: queryId
in: path
required: true
description: Query identifier for the result set to report on.
schema:
type: integer
- name: databaseId
in: query
required: false
description: Database identifier.
schema:
type: string
default: WOS
- name: reportLevel
in: query
required: false
description: Report aggregation level (WOS or AllDB).
schema:
type: string
enum:
- WOS
- AllDB
default: WOS
responses:
'200':
description: Successful response with citation report
content:
application/json:
schema:
$ref: '#/components/schemas/CitationReport'
'400':
description: Bad request or result set too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/category-context/{uniqueId}:
get:
summary: Web of Science Expanded Get Category Context for Record
description: >-
Retrieve the categorization context for citing and cited references of
a Web of Science article. Returns ASCA traditional category distribution
for the specified scope.
operationId: getCategoryContext
tags:
- reports
x-microcks-operation:
delay: 100
parameters:
- name: uniqueId
in: path
required: true
description: WOS unique identifier of the article.
schema:
type: string
example: WOS:000349044100001
- name: databaseId
in: query
required: false
description: Database identifier.
schema:
type: string
default: WOS
- name: citeType
in: query
required: false
description: Scope of category context (Citing, Referenced, or Aggregated).
schema:
type: string
enum:
- Citing
- Referenced
- Aggregated
default: Citing
responses:
'200':
description: Successful response with category context
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryContext'
'404':
description: Record not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-ApiKey
description: Clarivate API key for Web of Science API Expanded
schemas:
SearchRequest:
type: object
description: Search request body for POST endpoint
properties:
databaseId:
type: string
description: Database to search
default: WOS
usrQuery:
type: string
description: Advanced search query using WOS query syntax
count:
type: integer
description: Number of records to return
default: 10
firstRecord:
type: integer
description: Starting record number
default: 1
editions:
type: array
description: Database editions to search
items:
type: string
publishTimeSpan:
$ref: '#/components/schemas/TimeSpan'
sortField:
type: string
description: Sort field and direction
TimeSpan:
type: object
description: Date range for filtering
properties:
begin:
type: string
description: Start date in YYYY-MM-DD format
format: date
end:
type: string
description: End date in YYYY-MM-DD format
format: date
SearchResponse:
type: object
description: Response from search and retrieval operations
properties:
queryResult:
$ref: '#/components/schemas/QueryResult'
records:
$ref: '#/components/schemas/Records'
QueryResult:
type: object
description: Metadata about the search query and result set
properties:
queryId:
type: integer
description: Identifier for this query (for subsequent pagination calls)
recordsFound:
type: integer
description: Total number of records matching the query
recordsSearched:
type: integer
description: Number of records searched (may differ from total database size)
Records:
type: object
description: Container for record results
properties:
records:
type: array
description: Array of WOS records
items:
$ref: '#/components/schemas/WosRecord'
WosRecord:
type: object
description: A full Web of Science record with all metadata fields
properties:
UID:
type: string
description: Web of Science unique identifier
static_data:
$ref: '#/components/schemas/StaticData'
dynamic_data:
$ref: '#/components/schemas/DynamicData'
StaticData:
type: object
description: Static (non-citation) metadata for a WOS record
properties:
summary:
$ref: '#/components/schemas/RecordSummary'
fullrecord_metadata:
$ref: '#/components/schemas/FullRecordMetadata'
RecordSummary:
type: object
description: Summary fields of a WOS record
properties:
names:
type: object
description: Author and editor names
doctypes:
type: object
description: Document types
titles:
type: object
description: Titles (article, source, etc.)
pub_info:
$ref: '#/components/schemas/PubInfo'
identifiers:
type: object
description: Document identifiers (DOI, ISSN, etc.)
PubInfo:
type: object
description: Publication information
properties:
pubtype:
type: string
description: Publication type
pubyear:
type: string
description: Year of publication
sortdate:
type: string
description: Sort date
issue:
type: string
description: Issue number
vol:
type: string
description: Volume number
FullRecordMetadata:
type: object
description: Full record metadata including keywords and addresses
properties:
languages:
type: object
description: Publication language information
keywords:
type: object
description: Author keywords and Keywords Plus
addresses:
type: object
description: Author affiliation addresses
fund_ack:
type: object
description: Funding acknowledgment information
DynamicData:
type: object
description: Dynamic data including citation counts
properties:
citation_related:
type: object
description: Citation count information
properties:
tc_list:
type: object
description: Times-cited list by database
RecordIdsResponse:
type: object
description: Response containing only record UIDs
properties:
queryResult:
$ref: '#/components/schemas/QueryResult'
ids:
type: array
description: Array of WOS unique identifiers
items:
type: string
CitationReport:
type: object
description: Citation report for a query result set
properties:
timesCited:
type: integer
description: Total times cited for all records in the result set
averagePerItem:
type: number
description: Average citations per item
format: float
hIndex:
type: integer
description: h-index for the result set
citingArticlesLinks:
type: string
description: Link to citing articles
format: uri
yearPublished:
type: array
description: Year-by-year publication counts
items:
$ref: '#/components/schemas/YearCount'
citationsByYear:
type: array
description: Year-by-year citation counts
items:
$ref: '#/components/schemas/YearCount'
YearCount:
type: object
description: Count value for a specific year
properties:
year:
type: integer
description: Year
count:
type: integer
description: Count for that year
CategoryContext:
type: object
description: Category context for citing or referenced records
properties:
categories:
type: array
description: ASCA traditional categories with counts
items:
$ref: '#/components/schemas/CategoryCount'
CategoryCount:
type: object
description: A category with its record count
properties:
name:
type: string
description: Category name
count:
type: integer
description: Number of records in this category
ErrorResponse:
type: object
description: Error response from the API
properties:
code:
type: integer
description: HTTP error code
message:
type: string
description: Human-readable error message