Clarivate JSON API

openapi: 3.2.0
info:
  title: InCites Document Level Metrics JSON API
  description: The InCites API provides document level metrics from InCites to support integration with Institutional Repository (IR) and Current Research Information Systems (CRIS). Ask your account manager about subscribing to the InCites API, or contact our support team to let us know you are interested.
  version: 2.0.0
servers:
- url: https://incites-api.clarivate.com/api/incites
security:
- key: []
tags:
- name: Json
  description: Response in json format
paths:
  /DocumentLevelMetricsByInstitutionId/json:
    get:
      tags:
      - Json
      summary: Get metrics by institution Id
      description: Find all document level metrics for a given institution
      parameters:
      - name: X-ApiKey
        in: header
        description: Developer Key parameter, authenticates you to use the service and ties your institution id to the call. Previous versions of this API supported this as a query parameter with the key 'X-TR-API-APP-ID'. This construct will be supported for a time, but going forward, this parameter should be passed in the header
        required: true
        schema:
          type: string
      - name: year
        in: query
        description: Your response will contain records published starting in this year. Must be at least 1980
        required: true
        schema:
          type: string
      - name: recordcount
        in: query
        description: This is the maximum number of records that will be returned per request. Must be less than the limit placed on the developer key (default maximum is 100)
        required: true
        schema:
          type: integer
      - name: startingrecord
        in: query
        description: Starting index of Records returned. Used when number of Records required exceeds limit on single request. Starts at Index 1
        required: true
        schema:
          type: integer
      - name: ver
        in: query
        description: Always set to 2
        required: true
        schema:
          type: integer
      - name: schema
        in: query
        description: Retrieves schema specific metrics after passing over the corresponding code. Returns WoS categories if absent.
        examples:
          Search1:
            value: anvur
            summary: ANVUR
          Search2:
            value: for1
            summary: Australia ERA 2018 FOR Level 1
          Search3:
            value: for2
            summary: Australia ERA 2018 FOR Level 2
          Search4:
            value: capesl1
            summary: CAPES Level 1
          Search5:
            value: capesl2
            summary: CAPES Level 2
          Search6:
            value: capesl3
            summary: CAPES Level 3
          Search7:
            value: scadcl1
            summary: China SCADC Subject Categories 12 Broad levels
          Search8:
            value: scadcl2
            summary: China SCADC Subject Categories 77 Narrow levels
          Search9:
            value: ct
            summary: Citation Topics
          Search10:
            value: et
            summary: Emerging Topics
          Search11:
            value: esi
            summary: Essential Science Indicators
          Search12:
            value: fapesp
            summary: FAPESP
          Search13:
            value: gipp
            summary: GIPP
          Search14:
            value: kakenl2
            summary: KAKEN Level 2
          Search15:
            value: kakenl3
            summary: KAKEN Level 3
          Search16:
            value: oecd
            summary: OECD
          Search17:
            value: pl19
            summary: Polish classification of disciplines
          Search18:
            value: ris3
            summary: Research and Innovation Strategies for Specialization (RIS3)
          Search19:
            value: ref2008
            summary: UK REF 2008
          Search20:
            value: ref2014
            summary: UK REF 2014
          Search21:
            value: ref2021
            summary: UK REF 2021
          Search22:
            value: sdg
            summary: UN Sustainable Development Goals
          Search23:
            value: gras
            summary: Shanghai GRAS ranking
          Search24:
            value: wos
            summary: Web of Science
        schema:
          type: string
          default: wos
      - name: esci
        in: query
        description: Flag to return InCites baseline metrics with Emerging Sources Citation Index (ESCI) content. Accepts y/n case insensitive values only. y - returns InCites metrics with ESCI index, n - returns InCites metrics without ESCI index
        schema:
          type: string
          default: n
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfRecords'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: getDocumentLevelMetricsByInstitutionIdJson
      x-operation-id-source: derived
  /DocumentLevelMetricsByInstitutionIdRecordCount/json:
    get:
      tags:
      - Json
      summary: Get metrics count by year
      description: Input a year, and InCites API returns number of records unified to your institution. Used in conjunction with DocumentLevelMetricsByInstitutionId
      parameters:
      - name: X-ApiKey
        in: header
        description: Developer Key parameter, authenticates you to use the service and ties your institution id to the call. Previous versions of this API supported this as a query parameter with the key 'X-TR-API-APP-ID'. This construct will be supported for a time, but going forward, this parameter should be passed in the header
        required: true
        schema:
          type: string
      - name: year
        in: query
        description: Your response will contain records published starting in this year. Must be at least 1980
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: integer
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: getDocumentLevelMetricsByInstitutionIdRecordCountJson
      x-operation-id-source: derived
  /DocumentLevelMetricsByUT/json:
    get:
      tags:
      - Json
      summary: Get metrics by UT
      description: Find document level metrics for a given UT
      parameters:
      - name: X-ApiKey
        in: header
        description: Developer Key parameter, authenticates you to use the service and ties your institution id to the call. Previous versions of this API supported this as a query parameter with the key 'X-TR-API-APP-ID'. This construct will be supported for a time, but going forward, this parameter should be passed in the header
        required: true
        schema:
          type: string
      - name: UT
        in: query
        description: Submit a comma delimited list of UT values and get InCites metrics in the response. A valid UT is 15 alphanumeric digits. All trailing 0's must be left in the UT, and there should be no spaces between UTs. If there is no data for a UT or an invalid UT is entered, that UT will be ignored in the response. A limit of 100 UTs may be submitted per request. To see sample API results, use one or more of the following UTs 000352040700014,000353267900023,000346982900018,000346342200004
        required: true
        schema:
          type: string
      - name: ver
        in: query
        description: Always set to 2
        required: true
        schema:
          type: integer
      - name: schema
        in: query
        description: Retrieves schema specific metrics after passing over the corresponding code. Returns WoS categories if absent.
        examples:
          Search1:
            value: anvur
            summary: ANVUR
          Search2:
            value: for1
            summary: Australia ERA 2018 FOR Level 1
          Search3:
            value: for2
            summary: Australia ERA 2018 FOR Level 2
          Search4:
            value: capesl1
            summary: CAPES Level 1
          Search5:
            value: capesl2
            summary: CAPES Level 2
          Search6:
            value: capesl3
            summary: CAPES Level 3
          Search7:
            value: scadcl1
            summary: China SCADC Subject Categories 12 Broad levels
          Search8:
            value: scadcl2
            summary: China SCADC Subject Categories 77 Narrow levels
          Search9:
            value: ct
            summary: Citation Topics
          Search10:
            value: et
            summary: Emerging Topics
          Search11:
            value: esi
            summary: Essential Science Indicators
          Search12:
            value: fapesp
            summary: FAPESP
          Search13:
            value: gipp
            summary: GIPP
          Search14:
            value: kakenl2
            summary: KAKEN Level 2
          Search15:
            value: kakenl3
            summary: KAKEN Level 3
          Search16:
            value: oecd
            summary: OECD
          Search17:
            value: pl19
            summary: Polish classification of disciplines
          Search18:
            value: ris3
            summary: Research and Innovation Strategies for Specialization (RIS3)
          Search19:
            value: ref2008
            summary: UK REF 2008
          Search20:
            value: ref2014
            summary: UK REF 2014
          Search21:
            value: ref2021
            summary: UK REF 2021
          Search22:
            value: sdg
            summary: UN Sustainable Development Goals
          Search23:
            value: gras
            summary: Shanghai GRAS ranking
          Search24:
            value: wos
            summary: Web of Science
        schema:
          type: string
          default: wos
      - name: esci
        in: query
        description: Flag to return InCites baseline metrics with Emerging Sources Citation Index (ESCI) content. Accepts y/n case insensitive values only. y - returns InCites metrics with ESCI index, n - returns InCites metrics without ESCI index
        schema:
          type: string
          default: n
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfRecords'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: getDocumentLevelMetricsByUTJson
      x-operation-id-source: derived
  /CheckValidUTs/json:
    get:
      tags:
      - Json
      summary: Get invalid UTs
      description: Find invalid UT(s) from a given list of UTs
      parameters:
      - name: X-ApiKey
        in: header
        description: Developer Key parameter, authenticates you to use the service and ties your institution id to the call. Previous versions of this API supported this as a query parameter with the key 'X-TR-API-APP-ID'. This construct will be supported for a time, but going forward, this parameter should be passed in the header
        required: true
        schema:
          type: string
      - name: UT
        in: query
        description: Submit a comma delimited list of UT values and get InCites metrics in the response. A valid UT is 15 alphanumeric digits. All trailing 0's must be left in the UT, and there should be no spaces between UTs. If there is no data for a UT or an invalid UT is entered, that UT will be ignored in the response. A limit of 100 UTs may be submitted per request. To see sample API results, use one or more of the following UTs 000352040700014,000353267900023,000346982900018,000346342200004
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUTs'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: getCheckValidUTsJson
      x-operation-id-source: derived
  /InCitesLastUpdated/json:
    get:
      tags:
      - Json
      summary: Get last updated information
      description: Find out incites data set and wos data set index last update time
      parameters:
      - name: X-ApiKey
        in: header
        description: Developer Key parameter, authenticates you to use the service and ties your institution id to the call. Previous versions of this API supported this as a query parameter with the key 'X-TR-API-APP-ID'. This construct will be supported for a time, but going forward, this parameter should be passed in the header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfDates'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: getInCitesLastUpdatedJson
      x-operation-id-source: derived
components:
  schemas:
    Percentiles:
      type: object
      properties:
        SUBJECT:
          type: string
          description: Each Record has an index number corresponding to its position. Starts at index 1
          example: History Of Social Sciences
        CODE:
          type: string
          description: Unique identifier for Web of Science Core Collection article (UID)
          example: MR
        CATPERCENTILE:
          type: integer
          description: The percentile in which the paper ranks in its category and database year, based on total citations received by the paper. The higher the number of citations, the *higher* the percentile number
        IS_BEST:
          type: string
          description: Returns true if this category is the best
          example: 'true'
        CAT_EXP_CITATION:
          type: integer
          description: Citations expected for this document based on the citation received by documents published in the same year, document type and subject area
        CNCI:
          type: integer
          description: The Category Normalized Citation Impact (CNCI) of a document is calculated by dividing the actual count of citing items by the expected citation rate for documents with the same document type, year of publication and subject area
    OA_FLAG_DATA:
      type: object
      properties:
        TYPE:
          type: integer
          description: Impact Story colour
    ArrayOfDates:
      type: array
      items:
        type: object
        properties:
          INCITES_DATASET_UPDATED:
            type: string
            description: The date of the last time the InCites Dataset was updated
            example: 02-12-2018
          WOS_DATASET_INDEXED:
            type: string
            description: The date of the last time the WoS Dataset was updated
            example: 31/DEC/2017
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Error Code
        message:
          type: string
          description: Error Message
    ArrayOfUTs:
      type: array
      items:
        $ref: '#/components/schemas/UT'
    ArrayOfRecords:
      type: array
      items:
        $ref: '#/components/schemas/Record'
    Record:
      type: object
      properties:
        ACCESSION_NUMBER:
          type: string
          description: Unique identifier for Web of Science Core Collection article (UID)
          example: 000188396500010
        DOCUMENT_TYPE:
          type: string
          description: Bibliographic term denoting the type of article
          example: ARTICLE
        TIMES_CITED:
          type: integer
          description: Number of times an article has been cited
          example: 18
        JOURNAL_EXPECTED_CITATIONS:
          type: number
          description: Average number of citations to articles of the same document type from the same journal in the same database year
          example: 18.894930875576037
        JNCI:
          type: integer
          description: Citation impact (citations per paper) normalized for journal, year and document type subject
        IMPACT_FACTOR:
          type: number
          description: Average number of times articles from a journal published in the past two years have been cited in the JCR year
          example: 2.055
        HARMEAN_CAT_EXP_CITATION:
          type: number
          description: The harmonic mean of citation rate values for all research fields to which an article is assigned.  For more information about the citation rate metric, see the <a href='http://ipscience-help.thomsonreuters.com/inCites2Live/indicatorsGroup/aboutHandbook/usingCitationIndicatorsWisely/baselines.html'>InCites Help File</a>
          example: 37.894344329833984
        AVG_CNCI:
          type: number
          description: Citation impact (citations per paper) normalized for subject, year and document type
          example: 0.48
        ESI_HIGHLY_CITED_PAPER:
          type: integer
          description: Entities that are included in ESI (top 1% for authors and institutions, top 50% for nations and journals). 0=No; 1=Yes
          example: 0
        ESI_HOT_PAPER:
          type: integer
          description: The paper is an ESI Hot Paper, ranked in the top 1% by citations for field and age. 0=No; 1=Yes
          example: 0
        IS_INTERNATIONAL_COLLAB:
          type: integer
          description: Publication has at least two different countries among the affiliations of the co-authors. 0=No; 1=Yes
          example: 1
        IS_INSTITUTION_COLLAB:
          type: integer
          description: Indicates that more than one institution has contributed to the document. 0=No; 1=Yes
          example: 1
        IS_INDUSTRY_COLLAB:
          type: integer
          description: Papers that list their organization type as a corporate for one or more of the co-authors affiliations. 0=No; 1=Yes
          example: 0
        OPEN_ACCESS:
          type: object
          properties:
            OA_FLAG:
              type: integer
              description: The document is published in an Open Access journal. Open Access Journals in InCites 2.0 are identical to Open Access Journals in InCites JCR - Gold Open Access. 0=No; 1=Yes
              example: 1
            STATUS:
              type: array
              items:
                $ref: '#/components/schemas/OA_FLAG_DATA'
        RNUM:
          type: integer
          description: Each Record has an index number corresponding to its position. Starts at index 1
          example: 1
        PERCENTILE:
          type: array
          items:
            $ref: '#/components/schemas/Percentiles'
    UT:
      type: object
      properties:
        ISI_LOC:
          type: string
          description: Unique identifier for Web of Science Core Collection article (UID)
          example: 000188396500010
  securitySchemes:
    key:
      type: apiKey
      in: header
      name: X-ApiKey