Clarivate XML API

openapi: 3.2.0
info:
  title: InCites Document Level Metrics XML 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: XML
  description: Response in xml format
paths:
  /DocumentLevelMetricsByInstitutionId/xml:
    get:
      tags:
      - XML
      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/xml:
              example: "<?xml version='1.0' encoding='UTF-8' ?>\n<response xmlns='http://www.isinet.com/xrpc42'>\n\t<fn name='IncitesWebServices.getDocumentLevelMetricsByUT' rc='OK'>\n\t\t<list>\n\t\t\t<map>\n\t\t\t\t<val name='ACCESSION_NUMBER'>000077675600082</val>\n\t\t\t\t<val name='DOCUMENT_TYPE'>ARTICLE</val>\n\t\t\t\t<val name='TIMES_CITED'>0</val>\n\t\t\t\t<val name='IMPACT_FACTOR'>-1</val>\n\t\t\t\t<val name='HARMEAN_CAT_EXP_CITATION'>1.1968</val>\n\t\t\t\t<val name='JNCI'>2.49</val>\n\t\t\t\t<val name='AVG_CNCI'>0</val>\n\t\t\t\t<val name='ESI_HIGHLY_CITED_PAPER'>0</val>\n\t\t\t\t<val name='ESI_HOT_PAPER'>0</val>\n\t\t\t\t<val name='IS_INTERNATIONAL_COLLAB'>0</val>\n\t\t\t\t<val name='IS_INSTITUTION_COLLAB'>0</val>\n\t\t\t\t<val name='IS_INDUSTRY_COLLAB'>0</val>\n\t\t\t\t<val name='RNUM'>1</val>\n\t\t\t\t<list name='PERCENTILE'>\n\t\t\t\t\t<map>\n\t\t\t\t\t\t<val name='SUBJECT'>ONCOLOGY</val>\n\t\t\t\t\t\t<val name='CODE'>MR</val>\n\t\t\t\t\t\t<val name='CAT_PERC'>5.26</val>\n\t\t\t\t\t\t<val name='IS_BEST'>true</val>\n\t\t\t\t\t\t<val name='CNCI'>8.2231</val>\n\t\t\t\t\t\t<val name='CAT_EXP_CITATION'>13.694358825683594</val>\n\t\t\t\t\t</map>\n\t\t\t\t\t<map>\n\t\t\t\t\t\t<val name='SUBJECT'>ECONOMICS</val>\n\t\t\t\t\t\t<val name='CODE'>GY</val>\n\t\t\t\t\t\t<val name='CAT_PERC'>73.45</val>\n\t\t\t\t\t\t<val name='IS_BEST'>false</val>\n\t\t\t\t\t\t<val name='CNCI'>9.4199</val>\n\t\t\t\t\t\t<val name='CAT_EXP_CITATION'>29.480670928955078</val>\n\t\t\t\t\t</map>\n\t\t\t\t</list>\n\t\t\t\t<map name='OPEN_ACCESS'>\n\t\t\t\t\t<val name='OA_FLAG'>1</val>\n\t\t\t\t\t<list name='STATUS'>\n\t\t\t\t\t\t<map>\n\t\t\t\t\t\t\t<val name='TYPE'>GREEN PUBLISHED</val>\n\t\t\t\t\t\t</map>\n\t\t\t\t\t\t<map>\n\t\t\t\t\t\t\t<val name='TYPE'>OTHER GOLD</val> \n\t\t\t\t\t\t</map>\n\t\t\t\t\t</list>\n\t\t\t\t</map>\n\t\t\t</map>\n\t\t</list>\n\t</fn>\n</response>"
        '400':
          description: Bad request
          content: {}
        '500':
          description: Internal server error
          content: {}
      operationId: getDocumentLevelMetricsByInstitutionIdXml
      x-operation-id-source: derived
  /DocumentLevelMetricsByInstitutionIdRecordCount/xml:
    get:
      tags:
      - XML
      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/xml:
              schema:
                type: integer
              example: "<?xml version='1.0' encoding='UTF-8' ?>\n<response xmlns='http://www.isinet.com/xrpc42'>\n\t<fn name='IncitesWebServices.getNumPublicationsByInstitutionId' rc='OK'>\n\t\t<val>22922</val>\n\t</fn>\n</response>"
        '400':
          description: Bad request
          content: {}
        '500':
          description: Internal server error
          content: {}
      operationId: getDocumentLevelMetricsByInstitutionIdRecordCountXml
      x-operation-id-source: derived
  /DocumentLevelMetricsByUT/xml:
    get:
      tags:
      - XML
      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/xml:
              example: "<?xml version='1.0' encoding='UTF-8' ?>\n<response xmlns='http://www.isinet.com/xrpc42'>\n\t<fn name='IncitesWebServices.getDocumentLevelMetricsByUT' rc='OK'>\n\t\t<list>\n\t\t\t<map>\n\t\t\t\t<val name='ACCESSION_NUMBER'>000077675600082</val>\n\t\t\t\t<val name='DOCUMENT_TYPE'>ARTICLE</val>\n\t\t\t\t<val name='TIMES_CITED'>0</val>\n\t\t\t\t<val name='IMPACT_FACTOR'>-1</val>\n\t\t\t\t<val name='HARMEAN_CAT_EXP_CITATION'>1.1968</val>\n\t\t\t\t<val name='JNCI'>2.49</val>\n\t\t\t\t<val name='AVG_CNCI'>0</val>\n\t\t\t\t<val name='ESI_HIGHLY_CITED_PAPER'>0</val>\n\t\t\t\t<val name='ESI_HOT_PAPER'>0</val>\n\t\t\t\t<val name='IS_INTERNATIONAL_COLLAB'>0</val>\n\t\t\t\t<val name='IS_INSTITUTION_COLLAB'>0</val>\n\t\t\t\t<val name='IS_INDUSTRY_COLLAB'>0</val>\n\t\t\t\t<val name='RNUM'>1</val>\n\t\t\t\t<list name='PERCENTILE'>\n\t\t\t\t\t<map>\n\t\t\t\t\t\t<val name='SUBJECT'>ONCOLOGY</val>\n\t\t\t\t\t\t<val name='CODE'>MR</val>\n\t\t\t\t\t\t<val name='CAT_PERC'>5.26</val>\n\t\t\t\t\t\t<val name='IS_BEST'>true</val>\n\t\t\t\t\t\t<val name='CNCI'>8.2231</val>\n\t\t\t\t\t\t<val name='CAT_EXP_CITATION'>13.694358825683594</val>\n\t\t\t\t\t</map>\n\t\t\t\t\t<map>\n\t\t\t\t\t\t<val name='SUBJECT'>ECONOMICS</val>\n\t\t\t\t\t\t<val name='CODE'>GY</val>\n\t\t\t\t\t\t<val name='CAT_PERC'>73.45</val>\n\t\t\t\t\t\t<val name='IS_BEST'>false</val>\n\t\t\t\t\t\t<val name='CNCI'>9.4199</val>\n\t\t\t\t\t\t<val name='CAT_EXP_CITATION'>29.480670928955078</val>\n\t\t\t\t\t</map>\n\t\t\t\t</list>\n\t\t\t\t<map name='OPEN_ACCESS'>\n\t\t\t\t\t<val name='OA_FLAG'>1</val>\n\t\t\t\t\t<list name='STATUS'>\n\t\t\t\t\t\t<map>\n\t\t\t\t\t\t\t<val name='TYPE'>GREEN PUBLISHED</val>\n\t\t\t\t\t\t</map>\n\t\t\t\t\t\t<map>\n\t\t\t\t\t\t\t<val name='TYPE'>OTHER GOLD</val> \n\t\t\t\t\t\t</map>\n\t\t\t\t\t</list>\n\t\t\t\t</map>\n\t\t\t</map>\n\t\t</list>\n\t</fn>\n</response>"
        '400':
          description: Bad request
          content: {}
        '500':
          description: Internal server error
          content: {}
      operationId: getDocumentLevelMetricsByUTXml
      x-operation-id-source: derived
  /CheckValidUTs/xml:
    get:
      tags:
      - XML
      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/xml:
              example: "<?xml version='1.0' encoding='UTF-8' ?>\n<response xmlns='http://www.isinet.com/xrpc42'>\n\t<fn name='IncitesWebServices.getInvalidUTsList' rc='OK'>\n\t\t<list>\n\t\t\t<map>\n\t\t\t\t<val name='ISI_LOC'>test1</val>\n\t\t\t</map>\n\t\t\t<map>\n\t\t\t\t<val name='ISI_LOC'>test</val>\n\t\t\t</map>\n\t\t</list>\n\t</fn>\n</response>"
        '400':
          description: Bad request
          content: {}
        '500':
          description: Internal server error
          content: {}
      operationId: getCheckValidUTsXml
      x-operation-id-source: derived
  /InCitesLastUpdated/xml:
    get:
      tags:
      - XML
      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/xml:
              example: "<?xml version='1.0' encoding='UTF-8' ?>\n<response xmlns='http://www.isinet.com/xrpc42'>\n\t<fn name='IncitesWebServices.getInCitesDates' rc='OK'>\n\t\t<list>\n\t\t\t<map>\n\t\t\t\t<val name='INCITES_DATASET_UPDATED'>10-06-2017</val>\n\t\t\t\t<val name='WOS_DATASET_INDEXED'>31/Aug/2017</val>\n\t\t\t</map>\n\t\t</list>\n\t</fn>\n</response>"
        '500':
          description: Internal server error
          content: {}
      operationId: getInCitesLastUpdatedXml
      x-operation-id-source: derived
components:
  securitySchemes:
    key:
      type: apiKey
      in: header
      name: X-ApiKey