Web of Science SUSHI COUNTER5 API

{"swagger":"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 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"}},"host":"api.clarivate.com","basePath":"/api/counter/r5","schemes":["https"],"securityDefinitions":{"key":{"type":"apiKey","in":"header","name":"X-ApiKey"}},"paths":{"/status":{"get":{"operationId":"getAPIStatus","description":"This resource returns the current status of the reporting service supported by this API.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide report data for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"}],"responses":{"200":{"description":"Status of the reporting service(s) supported by this API.","schema":{"type":"array","items":{"$ref":"#/definitions/SUSHI_service_status"}}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/members":{"get":{"operationId":"getConsortiumMembers","description":"This resource returns the list of consortium members related to a Customer_ID.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide report data for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"}],"responses":{"200":{"description":"List of member accounts (sites) associated with the Customer_ID passed in as a parameter.","schema":{"type":"array","items":{"$ref":"#/definitions/SUSHI_consortium_member_list"}}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/reports":{"get":{"operationId":"getReports","description":"This resource returns a list of reports supported by the API for a given application.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide report data for.","required":true,"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,"type":"string"}],"responses":{"200":{"description":"List of reports supported by this service for this application.","schema":{"type":"array","items":{"$ref":"#/definitions/SUSHI_report_list"}}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/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","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide usage for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"},{"name":"begin_date","in":"query","description":"Usage start date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"},{"name":"end_date","in":"query","description":"Usage end date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"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,"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,"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,"type":"string"}],"responses":{"200":{"description":"Platform Master Report","schema":{"$ref":"#/definitions/COUNTER_platform_report"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/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.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide usage for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"},{"name":"begin_date","in":"query","description":"Usage start date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"},{"name":"end_date","in":"query","description":"Usage end date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"}],"responses":{"200":{"description":"Platform Usage [Standard View PR_P1]","schema":{"$ref":"#/definitions/COUNTER_platform_report"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/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.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide usage for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"},{"name":"begin_date","in":"query","description":"Usage start date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"},{"name":"end_date","in":"query","description":"Usage end date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"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,"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,"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,"type":"string"}],"responses":{"200":{"description":"Database Master Report","schema":{"$ref":"#/definitions/COUNTER_database_report"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/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.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide usage for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"},{"name":"begin_date","in":"query","description":"Usage start date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"},{"name":"end_date","in":"query","description":"Usage end date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"}],"responses":{"200":{"description":"Database Search and Item Usage [DR_D1], a Standard View of Database Master Report.","schema":{"$ref":"#/definitions/COUNTER_database_report"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}},"/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.","produces":["application/json"],"parameters":[{"name":"api_key","in":"query","description":"Developer key parameter, which authenticates you to use the service.","required":true,"type":"string"},{"name":"customer_id","in":"query","description":"Identifies the customer to provide usage for.","required":true,"type":"string"},{"name":"requestor_id","in":"query","description":"Identifies the requester (STeAM User Id) that is asking for report data","required":true,"type":"string"},{"name":"begin_date","in":"query","description":"Usage start date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"},{"name":"end_date","in":"query","description":"Usage end date in the form of yyyy-mm-dd or yyyy-mm.","required":true,"type":"string"}],"responses":{"200":{"description":"Database Access Denied [DR_D2], a Standard View of Database Master Report.","schema":{"$ref":"#/definitions/COUNTER_database_report"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/SUSHI_error_model"}}}}}},"definitions":{"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."}}},"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":"#/definitions/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":"#/definitions/SUSHI_error_model"}}}},"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_service_status":{"type":"object","required":["Service_Active"],"properties":{"Description":{"type":"string","description":"Description of the service.","example":"COUNTER Usage Reports for Web of Science platform."},"Service_Active":{"type":"boolean","description":"Indicator if the service is currently able to deliver reports.","example":true},"Registry_URL":{"type":"string","description":"If available, the URL separate registry with additional information about the service.","example":"https://www.projectcounter.org/counter-user/ebsco-database/"},"Note":{"type":"string","description":"A general note about the service.","example":"A given customer can request a maximum of 5 requests per day for a given report"},"Alerts":{"type":"array","description":"Any alerts related to service interruptions and status.","items":{"type":"object","properties":{"Date_Time":{"type":"string","format":"dateTime","description":"Date-time of the alert.","example":"2016-08-02: 12:54"},"Alert":{"type":"string","description":"Text of the alert.","example":"Service will be unavailable Sunday midnight..."}}}}}},"SUSHI_consortium_member_list":{"type":"object","required":["Customer_ID","Name"],"properties":{"Customer_ID":{"type":"string","description":"Identifer for the consortium's member account.  This identifier would be used as the Customer_ID for subsequent report requests for the member.","example":"1557c9eebf17b8fc56da59756791b636"},"Requestor_ID":{"type":"string","description":"The RequestorID to use to retrieve COUNTER stats the consortium's member account -- only include if different from the main consortium's RequestorID.  This identifier would be used as the Requestor for subsequent report requests for the member.","example":158},"Name":{"type":"string","description":"Customer name assigned to the consortium member.","example":"Mt. Laurel University Medical School"},"Notes":{"type":"string","description":"Additional notes regarding the customer.","example":"Usage pulled using content licensed by the consortium.","items":{"$ref":"#/definitions/SUSHI_org_identifiers"}}}},"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_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":"#/definitions/SUSHI_report_header"},"Report_Items":{"type":"array","items":{"$ref":"#/definitions/COUNTER_platform_usage"}}}},"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":"#/definitions/COUNTER_item_performance"},"description":"The usage data related to the report item"}}},"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":"#/definitions/SUSHI_report_header"},"Report_Items":{"type":"array","items":{"$ref":"#/definitions/COUNTER_database_usage"}}}},"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":"#/definitions/COUNTER_publisher_identifiers"},"description":"The identifier for the publisher."},"Performance":{"type":"array","items":{"$ref":"#/definitions/COUNTER_item_performance"},"description":"The usage data related to the report item"}}},"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}}}}}}},"security":[{"key":[]}]}