DataCite Support

Welcome to DataCite's support site. Here you will find helpful information about our services. We have included comprehensive technical guides, training materials, and tips to help you successfully use DataCite services. Use the search bar or browse the categories to find the information you are looking for!

EZ API

Recent Posts

Archive

DataCite Usage Reports API Guide

Usage for non-dataset materials

This guide outlines how to send usage reports for repository items that follow the COUNTER Code of Practice for Research Data. If you would like to submit usage reports for repository items that are NOT datasets, please contact us first at support@datacite.org.

Purpose

The DataCite Usage Reports API allows repositories to store data usage metrics. The API requires authentication for most writing endpoints but all reading endpoints are accessible without credentials. There is a Live API reference also available. To obtain credentials, your repository needs to be a Datacite client. Interested parties should contact the DataCite support team.

Authentication

All requests to the Usage Reports API require authentication for writing. For this reason, only traffic via a secure connection (HTTPS) is supported. The DataCite Usage Reports uses JWT authentication.

To start interacting with our DataCite Usage Reports API you must be a DataCite Provider or Client:

If you are a DataCite Provider, DataCite will provide you a JSON Web Token.

If you are a DataCite Client, your Provider will provide you a JSON Web Token.

JWT needs to be put in quotes

If you are using the command line remember to put your JWT in quotes.

How to Use

The DataCite Usage Reports API can be used directly by making HTTP requests with packages such as cURL.

Fetching Usage Reports

Let's start by testing our setup. In this guide, the examples we will use would employ the Usage Reports API Production endpoint (i.e., https://api.datacite.org ) We will use the curl command-line tool.

Now, open up a command prompt and enter the following command:

# GET /reports$ curl https://api.datacite.org/reports/

The response will be a list of all the reports. In this list only the headers of the reports is included. In the next step we will look at how to see the whole content of each report.

The response is a usage report in json format. We have truncated the report here to save space. The API expects SUSHI-formatted reports in ingestion and returns collections of SUSHI reports for consumption. The API closely follows the RESEARCH_DATA_SUSHI specification.

Register a Usage Report

To register a usage report you will need to generate a Data Usage report following the Code of practice for research data usage metrics. Additionally, the allowed and recommended characters for a URL-safe naming of parameters are defined in the format spec. To standardize parameter names, the following (more restrictive) rules are recommended:

Parameter names SHOULD start and end with the characters “a-z” (U+0061 to U+007A)

Parameter names SHOULD contain only the characters “a-z” (U+0061 to U+007A), “0-9” (U+0030 to U+0039), and the hyphen minus (U+002D HYPHEN-MINUS, “-“) as a separator between multiple words.

There are also a few tools you can use to generate your usage report based on your repository weblogs. For example, the Counter Processor is a Python 3 (written in 3.6.4) script for processing dataset access statistics from logs.

Once you have your usage report formatted, there are two ways to register a report:

Register a large Usage Report

Usage reports can get very large, so we have to ways to approach the submission of very large reports. The first approach is compression and the second is subsetting. Large reports need to be divided and compressed. We have set up a top limit of 50,000 datasets per report.