Metrics API
The Metrics API provides counts of downloads, datasets created, files uploaded, and more, as described below. The Dataverse Software also includes aggregate counts of Make Data Count metrics (described in the Make Data Count section of the Admin Guide and available per-Dataset through the Native API). A table of all the endpoints is listed below.
Contents:
Note
CORS The Metrics API can be used from scripts running in web browsers, as it allows cross-origin resource sharing (CORS).
Note
For all metrics besides Past Days Count (/pastDays/$days
) - recalculated daily, and (/toMonth/$month
) for prior months - never recalculated, the setting MetricsCacheTimeoutMinutes
defines how long the cached value will be returned by subsequent queries.
Categories
The Metrics API includes several categories of endpoints that provide different ways of understanding the evolution of metrics over time:
Total - an aggregate count over all-time:
Form: GET https://$SERVER/api/info/metrics/$type
where
$type
can be set, for example, todataverses
(Dataverse collections),datasets
,files
ordownloads
.Example:
curl https://demo.dataverse.org/api/info/metrics/downloads
Return: Most of these calls return a simple JSON object with a
count
whose value is the metric’s total count. Some calls, such asfiledownloads
return aggregate metrics per item (e.g. per file or by subject) as a JSONArray or CSV (see Return Formats below)
To-Month - a count of various objects in dataverse up to and including a specified month
$YYYY-DD
in YYYY-MM format (e.g.2018-01
):Form: GET https://$SERVER/api/info/metrics/$type/toMonth/$YYYY-DD
where
$type
can be set, for example, todataverses
(Dataverse collections),datasets
,files
ordownloads
.Example:
curl https://demo.dataverse.org/api/info/metrics/dataverses/toMonth/2018-01
Return: Most of these calls return a simple JSON object with a
count
whose value is the metric’s total count. One variant,/api/info/metrics/datasets/bySubject/toMonth
return aggregate metrics per Dataset Subject as a JSONArray or CSV (see Return Formats below)
Past Days - a count of various objects in a Dataverse installation for the past
$days
(e.g.30
):Form: GET https://$SERVER/api/info/metrics/$type/pastDays/$days
where
$type
can be set, for example, todataverses
(Dataverse collections),datasets
,files
ordownloads
.Example:
curl https://demo.dataverse.org/api/info/metrics/datasets/pastDays/30
Return: A simple JSON object with a
count
whose value is the metric’s total count.
Monthly - a time series of the metric with aggregate values per month with counts up to and including the given month:
where
$type
can be set, for example, todataverses
(Dataverse collections),datasets
,files
ordownloads
.Example:
curl https://demo.dataverse.org/api/info/metrics/downloads/monthly
Return: A JSON Array or CSV file with an array of counts per month. Variants of this this category that provide a time series per object return that information in the same formats (JSON array, CSV) with one time-series column per item (see Return Formats below).
Tree - endpoints that describe the structure of the tree of published Dataverses, as of now or as of the end of a specified month. The monthly version could be used to show growth of the Dataverse instance over time, but the initial use case for these endpoints was to provide a means to list the tree in a selection widget to scope the metrics displayed in the local Dataverse metrics page in the dataverse-metrics app.
Form: GET https://$SERVER/api/info/metrics/tree
or
Form: GET https://$SERVER/api/info/metrics/tree/toMonth/$YYYY-DD
Example:
curl https://demo.dataverse.org/api/info/metrics/tree
Return: A nested JSON array containing JSON objects for each Dataverse collection with key/values for id, ownerId, alias, depth, and name, and a JSON array containing analogous objects for Dataverse collections within the current one.
Return Formats
There are a number of API calls that provide time series, information reported per item (e.g. per dataset, per file, by subject, by category, and by file Mimetype), or both (time series per item). Because these calls all report more than a single number, the API provides two optional formats for the return that can be selected by specifying an HTTP Accept Header for the desired format:
application/json - a JSON array of objects. For time-series, the objects include key/values for the
date
andcount
for that month. For per-item calls, the objects include the item (e.g. for a subject), or it’s id/pid (for a dataset or datafile). For timeseries per-item, the objects also include a date. In all cases, the response is a single array.Example:
curl -H 'Accept:application/json' https://demo.dataverse.org/api/info/metrics/downloads/monthly
comma-separated-value (CSV) - a CSV file with rows corresponding to each JSON object in the application/json format. Column headers are included (e.g.
date,count
orsubject,count
ordate,pid,id,count
(for a time series per file)).Example:
curl -H 'Accept:text/csv' https://demo.dataverse.org/api/info/metrics/downloads/monthly
The default format is CSV, so
curl https://demo.dataverse.org/api/info/metrics/downloads/monthly
, or typing this URL into a browser return the CSV format.
Filtering with Query Parameters
To further tailor your metric, query parameters can be provided. On relevant endpoints, these query parameters can be used together.
parentAlias
Specifies which Dataverse sub-collection the metric should be collected for. Not including this parameter gathers metrics for the entire instance.
Example: curl https://demo.dataverse.org/api/info/metrics/datasets/?parentAlias=abc
would return the number of datasets in the Dataverse collection with alias ‘abc’ and in sub-collections within it.
dataLocation
Specifies whether the metric should query local
data, remote
data (e.g. harvested), or all
data when getting results. Only works for dataset metrics.
Example: curl https://demo.dataverse.org/api/info/metrics/datasets/?dataLocation=remote
country
The Make Data Count endpoints are also able to filter results by Country (specified using the ISO 3166 Country codes)
Example: curl https://demo.dataverse.org/api/info/metrics/makeDataCount/viewsTotal?country=au
Endpoint Table
The following table lists the available metrics endpoints (not including the Make Data Counts endpoints a single dataset which are part of the Native API) along with additional notes about them.