Usage Tracker API

Overview

The Usage Tracker API works with the DataCite Usage Tracker to log usage events. Usage events can be submitted directly to the Usage Tracker API endpoint.

This serves as an alternative option to using the embedded JavaScript tracker script or making manual calls to the JavaScript embed library with the data-autotrack option set to false. Direct API submission is intended only for cases where these other options are incompatible with a given technical environment.

Using the Usage Tracker API

• For each view or download event, send a request according to the /api/metric path.
• The Usage Tracker system was designed to work only with accurate Client IP and User Agent information, originally transmitted exclusively by an embedded JavaScript tracker. Therefore, accurate Client IP and User Agent information must be provided in the header of the API request in X-Forwarded-For User-Agent for view and download events to be properly logged and processed in alignment with the COUNTER Code of Practice for Research Data.
• The Usage Tracker API was originally designed only to be called by a browser-based script so that DataCite can define the requests as User and not Machine usage per the COUNTER specification. With direct Usage Tracker API event submissions, you are responsible for reporting User rather than Machine usage. If you would like to report machine usage, that should be submitted separately via the Usage Reports API (log processing method).
• We recommend reviewing the COUNTER Code of Practice and particularly the Processing Rules for Underlying COUNTER Reporting Data to understand the scope of user-intended usage that should be recorded as events. Several of the rules are automatically handled by the Usage Tracker system by processing transmitted user request information; for example, Double-Click Filtering and Internet Robots and Crawlers.

Testing

• See our Usage Tracker testing documentation for testing and evaluation strategies.
• Because usage reports are generated by the Usage Tracker system once per calendar month, view and download events submitted via the Usage Tracker API can be evaluated following the completion of a calendar month using the methods described in our documentation. The /api/check endpoint and the Usage Tracker API response can be used to confirm receipt of events in the interim.