Event Data is a joint service by Crossref and Datacite to collect and expose links to Crossref and DataCite DOIs. For DataCite DOIs Event Data provides links to other DOIs from DataCite, Crossref or other DOI registration agencies, as well as usage statistics sent to DataCite as usage reports.
The DataCite REST API provides a query API for the Event Data service, and allows users to retrieve events filtered by DOI or DOI prefix, source of the event, relation type of the event, and/or year and month the event occurred. See section Query Filters for details.
Linking events are relations between two DOIs, or a DOI and a URL. For DataCite DOIs these are described in DataCite metadata using the
<relatedIdentifier> property, and there is a controlled list of relation types that can be used (see section relation-type-id for details). Linking events describe a large number of relations, including
- granularity (is part of / has part)
There is no single relation type to describe citations, and relation types relevant for citations are sometimes used differently across organizations. The most commonly used relation types for citations are
Usage events (views and downloads of the content associated with a DOI) are provided by the
datacite-usage source, and are generated from usage reports in the standard SUSHI format sent to DataCite. Usage reports for datasets are generated using the Code of Practice for Research Data Usage Metrics and the SUSHI specification for research data usage metrics.
The usage reports summarize all usage events for a given month, and break them down into three categories:
- total vs. unique: for unique usage events accesses are only counted once per content item if they are within a unique user session.
- access method: track content usage by machines. The access method can be
- metric type: activities where content was retrieved (
requests) or information about content (e.g. metadata) was examined (
With these three categories there are 8 (2 x 2 x 2) relation types for usage events (see relation-type-id below).
The following filters are available in the Event Data Query API:
Query for any event information.
The identifier for the event subject, expressed as URL. For example
The identifier for the event object, expressed as URL. For example
obj-id of the event, expressed as DOI. For example
The DOI prefix of the
obj-id of the event. For example
The year and month in which the event occurred, in the format
YYYY-MM. For example
Usage Events for DataCite DOIs
Usage Reports submitted to DataCite
DataCite DOI as related identifier from DataCite metadata
Crossref DOI as related identifier in DataCite metadata
KISTI DOI as related identifier in DataCite metadata
OP DOI as related identifier in DataCite metadata
mEDRA DOI as related identifier in DataCite metadata
ISTIC DOI as related identifier in DataCite metadata
Crossref Funder ID as funder identifier in DataCite metadata
URL as related identifier in DataCite metadata
DataCite DOI in Crossref Metadata
datacite-usage events use one of these relation-types:
For events generated from DataCite metadata, the
relationType from the DataCite Metadata Schema is used:
datacite-funder uses the relation type
crossref uses the relation type
The DataCite Event Data Query API by default returns 1000 events per query. This number can be adjusted by the
page[size] query parameter, and must be between 0 and 1,000. For
page[size]=0 only the
meta object is returned.
To paginate through up to 10,000 results, the
page[number] query parameter can be used.
For query results with more than 1,000 events, e.g. to harvest all events from a particular source or for a particular prefix, cursor-based pagination should be used. The DataCite Event Data Query API returns a
links JSON object, use the URL in the
next property to fetch the next page, and this URL includes a
page[cursor] query parameter. With cursor-based pagination all events are retrieved in chronological order (using the
timestamp property), oldest events first. The cursor used is the UNIX epoch time, i.e. the number of seconds passed since 1 January 1970.
By default all events are sorted in ascending chronological order (using the last updated timestamp). Other sort criteria are:
- relevance: the relevance score of the query
- obj-id: the obj-id of each event
- total: total count of each event. Is > 1 only for usage events.
- created: using the timestamp when the event was created in the DataCite Event Data Query API
With the exception of
relevance, events can be sorted in descending order by prefixing the sort parameter with a minus sign, e.g.
-total. When using a sort parameter, only the first 10,000 events can be retrieved, as pagination based on page number is used.
The DataCite Event Data Query API returns statistics in a
meta JSON object, with the following properties:
- total: the total number of events found for this query (the API only shows 1,000 events at a time)
- total-pages: the number of API calls needed to return all results (fetching 1,000 events at a time)
- sources: the sources for the events found in this query, and the number of events per source
- prefixes: the DOI prefixes for the events found in this query, and the number of events per prefix, for up to 50 prefixes
- relation types: the relation types for the events found in this query, and the number of events per relation type, further broken down by year and month