Clarivate Reports API

openapi: 3.2.0
info:
  description: This API helps you harvest usage statistics from the Web of Science platform via the NISO SUSHI protocol in accordance with the COUNTER R5 Code of Practice
  version: 1.0.0
  title: Web of Science SUSHI COUNTER5 Reports API
  termsOfService: https://clarivate.com/wp-content/uploads/dlm_uploads/2018/12/End-User-Terms.pdf
  contact:
    name: Clarivate Customer Support
    email: https://support.clarivate.com/ScientificandAcademicResearch/s/?language=en_US
servers:
- url: https://api.clarivate.com/api/counter/r5
security:
- key: []
tags:
- name: Reports
paths:
  /reports:
    get:
      operationId: getReports
      description: This resource returns a list of reports supported by the API for a given application.
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide report data for.
        required: true
        schema:
          type: string
      - name: search
        in: query
        description: Keyword search filtered against report name. Allows for searching for a report by name (DR, DR_D1, DR_D2, PR or PR_P1)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of reports supported by this service for this application.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SUSHI_report_list'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get reports
      x-summary-source: derived
  /reports/pr:
    get:
      operationId: getPRReport
      description: This resource returns COUNTER 'Platform Usage' [pr]. COUNTER Platform Master Report (PR). A customizable report summarizing activity across Web of Science that allows the user to apply filters and select other configuration options
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide usage for.
        required: true
        schema:
          type: string
      - name: requestor_id
        in: query
        description: Identifies the requester (STeAM User Id) that is asking for report data
        required: true
        schema:
          type: string
      - name: begin_date
        in: query
        description: Usage start date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: Usage end date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: metric_type
        in: query
        description: Optional Report Filter. A list of Metric_Types to return. Specify multiple values by delimiting with a | character. Omitting this parameter will return all metric_types with statistics.
        required: false
        schema:
          type: string
      - name: granularity
        in: query
        description: Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals'
        required: false
        schema:
          type: string
      - name: attributes_to_show
        in: query
        description: Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values).  Multiple attribute names are delimited with a | character. Options include Data_Type and Access_Method
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Platform Master Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/COUNTER_platform_report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get PR report
      x-summary-source: derived
  /reports/pr_p1:
    get:
      operationId: getPRP1Report
      description: This resource returns COUNTER 'Platform Usage' [pr_p1]. This is a Standard View of the Package Master Report that presents usage for the overall Platform broken down by Metric_Type.
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide usage for.
        required: true
        schema:
          type: string
      - name: requestor_id
        in: query
        description: Identifies the requester (STeAM User Id) that is asking for report data
        required: true
        schema:
          type: string
      - name: begin_date
        in: query
        description: Usage start date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: Usage end date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Platform Usage [Standard View PR_P1]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/COUNTER_platform_report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get PRP1 report
      x-summary-source: derived
  /reports/dr:
    get:
      operationId: getDRReport
      description: This resource returns Database Master Report (DR). A customizable report detailing activity by database that allows the user to apply filters and select other configuration options.
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide usage for.
        required: true
        schema:
          type: string
      - name: requestor_id
        in: query
        description: Identifies the requester (STeAM User Id) that is asking for report data
        required: true
        schema:
          type: string
      - name: begin_date
        in: query
        description: Usage start date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: Usage end date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: metric_type
        in: query
        description: Optional Report Filter. A list of Metric_Types to return. Specify multiple values by delimiting with a | character. Omitting this parameter will return all metric_types with statistics.
        required: false
        schema:
          type: string
      - name: granularity
        in: query
        description: Optional Report Attribute. Include this parameter to allow usage to be retrieved with a granularity of 'month' (default if omitted) or 'totals'
        required: false
        schema:
          type: string
      - name: attributes_to_show
        in: query
        description: Optional Report Attribute. A list of attributes to include as separate elements in response (usage will be broken out by attribute values).  Multiple attribute names are delimited with a | character. Options include Data_Type and Access_Method
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Database Master Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/COUNTER_database_report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get DR report
      x-summary-source: derived
  /reports/dr_d1:
    get:
      operationId: getDRD1Report
      description: This resource returns COUNTER 'Database Search and Item Usage' [DR_D1], a Standard View of Database Master Report. Reports on key search and request metrics needed to evaluate a database.
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide usage for.
        required: true
        schema:
          type: string
      - name: requestor_id
        in: query
        description: Identifies the requester (STeAM User Id) that is asking for report data
        required: true
        schema:
          type: string
      - name: begin_date
        in: query
        description: Usage start date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: Usage end date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Database Search and Item Usage [DR_D1], a Standard View of Database Master Report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/COUNTER_database_report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get DRD1 report
      x-summary-source: derived
  /reports/dr_d2:
    get:
      operationId: getDRD2Report
      description: This resource returns COUNTER 'Database Access Denied' [DR_D2], a Standard View of Database Master Report. Reports on Access Denied activity for databases where users were denied access because simultaneous use licenses were exceeded or their institution did not have a license for the database.
      parameters:
      - name: api_key
        in: query
        description: Developer key parameter, which authenticates you to use the service.
        required: true
        schema:
          type: string
      - name: customer_id
        in: query
        description: Identifies the customer to provide usage for.
        required: true
        schema:
          type: string
      - name: requestor_id
        in: query
        description: Identifies the requester (STeAM User Id) that is asking for report data
        required: true
        schema:
          type: string
      - name: begin_date
        in: query
        description: Usage start date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: Usage end date in the form of yyyy-mm-dd or yyyy-mm.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Database Access Denied [DR_D2], a Standard View of Database Master Report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/COUNTER_database_report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SUSHI_error_model'
      tags:
      - Reports
      summary: Get DRD2 report
      x-summary-source: derived
components:
  schemas:
    COUNTER_database_report:
      type: object
      description: Describes the formatting needs for the COUNTER Database Report - the Report_Header and Report_Items (usage stats).
      required:
      - Report_Header
      - Report_Items
      properties:
        Report_Header:
          $ref: '#/components/schemas/SUSHI_report_header'
        Report_Items:
          type: array
          items:
            $ref: '#/components/schemas/COUNTER_database_usage'
    SUSHI_org_identifiers:
      type: object
      description: Identifier for an organization.
      required:
      - Type
      - Value
      properties:
        Type:
          type: string
          description: Type of identifier (namespace or domain). e.g. ISNI, Proprietary, etc.
          example: ISNI
          enum:
          - ISNI
          - ISIL
          - OCLC
          - Proprietary
        Value:
          type: string
          description: Value of the organization identifier
          example: 1234 1234 1234 1234
    COUNTER_database_usage:
      type: object
      description: Defines the output for the Report_Items being returned in a Database Report.
      required:
      - Database
      - Publisher
      - Platform
      - Performance
      properties:
        Database:
          type: string
          description: Name of the database or collection being reported on.
          example: Web of Science Core Collection
        Platform:
          type: string
          description: Name of the platform
          example: Web of Science
        Publisher:
          type: string
          description: Name of the organization that creates the database
          example: Clarivate
        Publisher_ID:
          type: array
          items:
            $ref: '#/components/schemas/COUNTER_publisher_identifiers'
          description: The identifier for the publisher.
        Performance:
          type: array
          items:
            $ref: '#/components/schemas/COUNTER_item_performance'
          description: The usage data related to the report item
    COUNTER_platform_report:
      type: object
      description: Describes the formatting needs for the COUNTER Platform Report - the Report_Header and Report_Items (usage stats).
      required:
      - Report_Header
      - Report_Items
      properties:
        Report_Header:
          $ref: '#/components/schemas/SUSHI_report_header'
        Report_Items:
          type: array
          items:
            $ref: '#/components/schemas/COUNTER_platform_usage'
    SUSHI_report_header:
      type: object
      description: Generalized report header that defines the requested report, the requestor, the customer, filters applied, reportAttributes applied and any exceptions.
      required:
      - Report_ID
      - Report_Name
      - Release
      properties:
        Created:
          type: string
          format: dateTime
          description: Time the report was prepared. Format as defined by date-time - RFC3339
          example: '2016-09-08T22:47:31Z'
        Created_By:
          type: string
          description: Name of the organization producing the report.
          example: Clarivate
        Customer_ID:
          type: string
          description: Identifier of the customer the report represents - identifier used on the request
          example: '12345'
        Report_ID:
          type: string
          description: The report ID or code or shortname. Typically this will be the same code provided in the Report parameter of the request.
          example: TR_J1
        Release:
          type: string
          description: The release or version of the report.
          example: '5'
        Report_Name:
          type: string
          description: The long name of the report.
          example: Journal Requests (Excluding "OA_Gold")
        Institution_Name:
          type: string
          description: Name of the customer.
          example: Mt. Laurel University
          items:
            $ref: '#/components/schemas/SUSHI_org_identifiers'
        Report_Filters:
          type: array
          description: A List of report filters used for this report.  Typically reflect filters provided on the Request.  Filters limit the data to be reported on.
          items:
            required:
            - Name
            - Value
            properties:
              Name:
                type: string
                description: Name of the report filter.
                example: Begin_Date
              Value:
                type: string
                description: Value of the report filter.
                example: '2015-01-01'
        Report_Attributes:
          type: array
          description: Any additional attributes applied to the report. Attributes inform the level of detail in the report.
          items:
            required:
            - Name
            - Value
            properties:
              Name:
                type: string
                description: Name of the report attribute.
                example: Granularity
              Value:
                type: string
                description: Value of the report attribute.
                example: Totals
        Exceptions:
          type: array
          description: Series of exceptions encounted when preparing the report.
          items:
            $ref: '#/components/schemas/SUSHI_error_model'
    COUNTER_platform_usage:
      type: object
      description: Defines the output for the Report_Items being returned in a Platform Report.
      required:
      - Platform
      - Performance
      properties:
        Platform:
          type: string
          description: Name of the platform
          example: Web of Science
        Performance:
          type: array
          items:
            $ref: '#/components/schemas/COUNTER_item_performance'
          description: The usage data related to the report item
    SUSHI_report_list:
      type: object
      required:
      - Report_ID
      - Report_Name
      - Release
      - Report_Description
      properties:
        Report_Name:
          type: string
          description: The long name of the report
          example: Database Search and Item Usage
        Report_ID:
          type: string
          description: The code, ID or short name of the report that is be used in the request to identify the report.
          example: DR_D1
        Release:
          type: string
          description: The release or version number of the report.
          example: '5'
        Report_Description:
          type: string
          description: A short sentence describing the report.
          example: Total and Monthly Searches and Item Usage for each Web of Science Database
        Path:
          type: string
          description: The path to use when requesting this report on this service. Optional but recommended for custom reports.
          example: /reports/dr_d1
    SUSHI_error_model:
      type: object
      description: Generalized format for presenting errors and exceptions.
      required:
      - Code
      - Severity
      - Message
      properties:
        Code:
          type: integer
          format: int32
          description: Error number. See table of error.
          example: 3040
        Severity:
          type: string
          description: Severity of the error.
          example: Warning
          enum:
          - Warning
          - Error
          - Fatal
          - Debug
          - Info
        Message:
          type: string
          description: Text describing the error.
          example: Partial Data Returned.
        Help_URL:
          type: string
          description: URL describing error details.
        Data:
          type: string
          description: Additional data provided by the server to clarify the error.
          example: Usage data has not been processed for all requested months.
    COUNTER_publisher_identifiers:
      type: object
      required:
      - Type
      - Value
      properties:
        Type:
          type: string
          example: ISNI
          enum:
          - ISNI
          - Proprietary
        Value:
          type: string
          description: Value of the publisher identifier
          example: 1234 1234 1234 1234
    COUNTER_item_performance:
      type: object
      required:
      - Period
      - Instance
      properties:
        Period:
          type: object
          required:
          - Begin_Date
          - End_Date
          properties:
            Begin_Date:
              type: string
              description: Beginning date for usage in this 'itemPerformance' instance.
              example: '2015-01-01'
            End_Date:
              type: string
              description: Ending date for usage in this 'itemPerformance' instance.
              example: '2015-01-31'
        Instance:
          type: array
          items:
            type: object
            required:
            - Metric_Type
            - Count
            properties:
              Metric_Type:
                type: string
                description: Type of activity being counted.
                example: Total_Item_Requests
                enum:
                - Searches_Automated
                - Searches_Federated
                - Searches_Platform
                - Searches_Regular
                - Total_Item_Investigations
                - Total_Item_Requests
                - Unique_Item_Investigations
                - Unique_Item_Requests
                - Unique_Title_Investigations
                - Unique_Title_Requests
                - No_License
                - Limit_Exceeded
              Count:
                type: integer
                description: Usage count > 0.  If count is zero, the Intance element should be excluded.
                example: 21
  securitySchemes:
    key:
      type: apiKey
      in: header
      name: X-ApiKey