Analytics

Analytics Overview

Revelator’s Analytics API data provides consumption (trends) and revenue data.

For analytics with multiple options for aggregation, granularity, and filtering, see Comprehensive Analytics.

For a lightweight endpoint with various pre-calculated, enterprise-level metrics, see Keymetrics.

Comprehensive Analytics

The primary analytics endpoints follow a standardized URL template with interchangeable components.

/analytics/{dataSet}/{aggregationDimension}?dateGranularity={granularity} …

metadata will be different, based on the aggregationDimension and can be implemented as a generic type with a metadata type parameter - AnalyticsResonseItem<TMetadata> using a different TMetadata for each aggregationDimension.
date should be excluded or null if dateGranularity is null or all
The filter dimensions (track, release, etc) are not included in the response data. These are only allowed as filters on the source data before dimension and date aggregation is applied. The response is always post aggregation when these values are no longer available.

Analytics Query components

Component	Passed as	Description
Data Set required	URL parameter	Data range to be aggregated. Currently supports: `trends` (consumption) `revenue`
Aggregation Dimension required	URL parameter	Data grouping dimension. Currently supports: `byCountry` `byDistributor` `byTrack` `byDeliveryType`
Date Granularity optional	Querystring parameter: `dateGranularity`	Filter Level of date grouping. Options are: Daily Monthly Yearly All `null` to not aggregate by date
Filter optional	Querystring parameters: `releaseId` `trackId` `artistId` `labelId` `enterpriseId`	Filter to be applied to the `dataSet` before grouping. This filter can include properties which are not exposed in the final response.
Page optional	Querystring parameters: `pageSize` `pageNumber`	Controls the amount of response data provided.
Order optional	Querystring parameters: `orderByDescending` (boolean) `orderByProperty` (any property, such as `streamcount`)	Controls how the response data is ordered, and by what property.

Example

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byDistributor?fromDate=2000-01-01&toDate=2000-12-31&dateGranularity=monthly&releaseIds=[1,2]&pageSize=9&pageNumber=1' \
     -H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

{
    "totals": {
        "streamsCount": 1,
        "downloadsCount": 1
    },
    "fromDate": "2000-01-01",
    "toDate": "2000-12-31",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 9,
    "items": [
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 1,
                "distributorName": "Apple"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 10,
                "distributorName": "Spotify"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 11,
                "distributorName": "Deezer"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 17,
                "distributorName": "Amazon Music"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 18,
                "distributorName": "Rhapsody / Napster"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 19,
                "distributorName": "YouTube"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 45,
                "distributorName": "Yandex"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 47,
                "distributorName": "Beleive"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 11,
                "distributorName": "Deezer"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        }
    ]
}

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byDistributor?fromDate=2000-01-01&toDate=2000-12-31&dateGranularity=all&releaseIds=[1,2]&pageSize=9&pageNumber=1' \
     -H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

{
    "totals": {
        "streamsCount": 1,
        "downloadsCount": 1
    },
    "fromDate": "2000-01-01",
    "toDate": "2000-12-31",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 9,
    "items": [
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 1,
                "distributorName": "Apple"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 10,
                "distributorName": "Spotify"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 11,
                "distributorName": "Deezer"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 17,
                "distributorName": "Amazon Music"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 18,
                "distributorName": "Rhapsody / Napster"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 19,
                "distributorName": "YouTube"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 45,
                "distributorName": "Yandex"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 47,
                "distributorName": "Beleive"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        },
        {
            "date": "2000-01-01",
            "metadata":
            {
                "distributorId": 11,
                "distributorName": "Deezer"
            },
            "streams": 1,
            "downloads": 1,
            "others": 1
        }
    ]
}

Keymetrics

The following endpoints can be used to receive analytics metrics, aggregated by date; Revenue data (segregated monthly) and Trends data (segregated daily).

GET `/analytics/trends/metricsByDate`

Retrieves trends analytics data, one object per every day, within the selected date range

Request Body

Parameter	Type	Description
`fromDate` optional	string	The start date for the date range provided in the response. Defaults to the most current date with values. Format is `yyyy-mm-dd`.
`toDate` optional	string	The end date for the date range provided in the response. Defaults to the most current date with values. Format is `yyyy-mm-dd`.
`metrics` optional	string	Defaults to all available metrics. When one or more metrics are provided, only those metrics data will appear in the response. Example: `metrics=totalStreams`

The response will be an array of 4 objects, one object each for November 2nd, 3rd, 4th and 5th.

Each object will contain only the totalStreams data, in the metrics array.

GET `/analytics/revenue/metricsByDate`

Retrieves revenue analytics data, one object per every month, within the selected date range

Parameter	Type	Description
`fromDate` optional	string	The start date for the date range provided in the response. Defaults to the most current date with values. Format is `yyyy-mm-dd`. As Revenue data is segregated monthly, this range should always include the first of the month of the desired date.
`toDate` optional	string	The end date for the date range provided in the response. Defaults to the most current date with values. Format is `yyyy-mm-dd`. As Revenue data is segregated monthly, this range should always include the first of the month of the desired date.
`metrics` optional	string	Defaults to all available metrics. When one or more metrics are provided, only those metrics data will appear in the response. Example: `metrics=dayRevenueQuantity`

The response will be an array of 2 objects, one object each for November 1st and for December 1st.

Each object will include only the totalRevenue and totalRevenueQuantity metrics data, in the metrics array.

Example

Request

curl -X GET -H 'Accept: text/plain'\ 
'https://api.revelator.com/analytics/trends/metricsByDate/?fromDate=2021-11-02&toDate=2021-11-05&metrics=totalStreams'

Request

curl -X GET -H 'Accept: text/plain'\ 
'https://api.revelator.com/analytics/revenue/metricsByDate/?fromDate=2021-11-02&toDate=2021-12-09&metrics=totalRevenue&metrics=dayRevenueQuantity'

V3 Analytics (beta)

With the goal of providing a more comprehensive analytics solution, we have launched a new version of the Revelator Analytics API (v3).

This is a beta version of the API. Please reach out to us if there are any issues.

The V3 API currently includes only the consumption data endpoint. More endpoints matching their V2 counterparts, as well as brand new endpoints, will be added in the future.

GET `/analytics/consumption/{aggregation}`

Retrieves consumption data aggregated by different dimensions.

Available Aggregation Dimensions

byArtist
byCountry
byDate
byDeliveryType
byDiscoveryType
byDistributor
byLabel
byRecordingVersion
byRelease
bySourceOfStream
byTrack

Notes:

The byDate endpoint does not have the metadata object in the items.
For date granularity, items are returned in the metrics object.
If an asset does not have streams/downloads for a date (day, week, month, quarter), the date is returned with a value of 0.
When using multiple filters of the same type, separate properties must be provided (e.g., releaseIds=2384320&releaseIds=1628168).

Query Params

Parameter	Type	Description
`fromDate` required	string	Start date for the data range (`yyyy-mm-dd`)
`toDate` required	string	End date for the data range (`yyyy-mm-dd`)
`dateGranularity` optional	string	Date granularity for results. Possible values: `Daily`, `Weekly`, `Monthly`, `Yearly`, `All`, `Null`
`pageSize` optional	integer	Number of items per page
`pageNumber` optional	integer	Page number for pagination
`orderByProperty` optional	string	Property to order results by
`orderByDescending` optional	boolean	Whether to order results in descending order

Filters (also provided as query params)

Filter	Type	Description	Applicable Aggregations
`releaseIds`	array of integers	Filter by release IDs	All
`trackIds`	array of integers	Filter by track IDs	All
`artistIds`	array of integers	Filter by artist IDs	All
`labelIds`	array of integers	Filter by label IDs	All
`distributorIds`	array of integers	Filter by distributor IDs	All
`excludeDistributorIds`	array of integers	Exclude specific distributor IDs	All
`excludeTikTok`	boolean	Exclude TikTok data	All
`countryIds`	array of integer	Filter by country IDs	byArtist, byCountry, byDate, byLabel, byRelease, byTrack
`deliveryTypeIds`	array of integers	Filter by delivery type IDs	byDeliveryType
`discoveryTypeIds`	array of integers	Filter by discovery type IDs	byDiscoveryType
`recordingVersionTypeIds`	array of integers	Filter by recording version type IDs	byRecordingVersion
`sourceOfStreamIds`	array of integers	Filter by source of stream IDs	bySourceOfStream

Response

Parameter	Type	Description
`totals`	object	Totals for the entire request
`totals.streamsCount`	integer	Total count for streams
`totals.trackDownloadCount`	integer	Total count for track downloads
`totals.releaseDownloadCount`	integer	Total count for release downloads
`fromDate`	string	Start date of the data range
`toDate`	string	End date of the data range
`totalItemsCount`	integer	Total number of items in the result set
`pageNumber`	integer	Current page number
`pageSize`	integer	Number of items per page
`items`	array	Resulting array of consumption data items
`items.metadata`	object	Metadata for the item. This value changes depending on the aggregation dimension (`null` if `byDate` aggregation is used)
`items.metrics`	object	Metrics
`items.metrics.streamsCount`	integer	Count for streams
`items.metrics.trackDownloadCount`	integer	Count for track downloads
`items.metrics.releaseDownloadCount`	integer	Count for release downloads
`items.metrics.eventDate`	string	Date of the event (`null` if not applicable)

Examples

Request

curl 'https://api.revelator.com/analytics/consumption/byRelease?excludeTikTok=true&fromDate=2024-07-24&pageNumber=1&pageSize=5000&releaseIds=2384320&releaseIds=1628168&releaseIds=2343290&toDate=2024-08-22' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

{
  "totals": {
    "streamsCount": 24075031,
    "trackDownloadsCount": 0,
    "releaseDownloadsCount": 0
  },
  "fromDate": "2024-07-24",
  "toDate": "2024-08-22",
  "totalItemsCount": 3,
  "pageNumber": 1,
  "pageSize": 3,
  "items": [
    {
      "metadata": {
        "version": null,
        "id": 1628169,
        "name": "Example name"
      },
      "metrics": [
        {
          "streamsCount": 7254872,
          "trackDownloadsCount": 0,
          "releaseDownloadsCount": 0,
          "eventDate": null
        }
      ]
    },
    // ... more items ...
  ]
}

Request

curl 'https://api.revelator.com/analytics/consumption/byRelease?dateGranularity=DAILY&excludeTikTok=true&fromDate=2024-07-24&pageNumber=1&pageSize=5000&releaseIds=2384320&releaseIds=1628168&releaseIds=2343290&toDate=2024-08-22' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

{
    "totals": {
        "streamsCount": 24075031,
        "trackDownloadsCount": 0,
        "releaseDownloadsCount": 0
    },
    "fromDate": "2024-07-24",
    "toDate": "2024-08-22",
    "totalItemsCount": 3,
    "pageNumber": 1,
    "pageSize": 3,
    "items": [
        {
            "metadata": {
                "version": null,
                "id": 2384322,
                "name": "Example name"
            },
            "metrics": [
                {
                    "streamsCount": 305813,
                    "trackDownloadsCount": 0,
                    "releaseDownloadsCount": 0,
                    "eventDate": "2024-07-24T00:00:00"
                },
                {
                    "streamsCount": 286907,
                    "trackDownloadsCount": 0,
                    "releaseDownloadsCount": 0,
                    "eventDate": "2024-07-25T00:00:00"
                },

                // ... more metrics  ...
            ]
        },
        // ... more items ...
    ]
}

Request

curl 'https://api.revelator.com/analytics/consumption/byDate?dateGranularity=DAILY&excludeTikTok=true&fromDate=2024-07-24&pageNumber=1&pageSize=5000&releaseIds=2384320&releaseIds=1628168&releaseIds=2343290&toDate=2024-08-22' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'

Response

{
    "totals": {
        "streamsCount": 10919427,
        "trackDownloadsCount": 0,
        "releaseDownloadsCount": 0
    },
    "fromDate": "2024-07-24",
    "toDate": "2024-08-22",
    "totalItemsCount": 30,
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metrics": [
                {
                    "streamsCount": 305813,
                    "trackDownloadsCount": 0,
                    "releaseDownloadsCount": 0,
                    "eventDate": "2024-07-24T00:00:00"
                },
                {
                    "streamsCount": 286907,
                    "trackDownloadsCount": 0,
                    "releaseDownloadsCount": 0,
                    "eventDate": "2024-07-25T00:00:00"
                },
            ]
        },
        // ... more items ...
    ]
}

Distribution

Rights

Analytics

Analytics Overview

Comprehensive Analytics

Analytics Query components

Example

Request

Response

Request

Response

Keymetrics

GET /analytics/trends/metricsByDate

Request Body

GET /analytics/revenue/metricsByDate

Example

Request

Request

V3 Analytics (beta)

GET /analytics/consumption/{aggregation}

Query Params

Filters (also provided as query params)

Response

Examples

Request

Response

Request

Response

Request

Response

GET `/analytics/trends/metricsByDate`

GET `/analytics/revenue/metricsByDate`

GET `/analytics/consumption/{aggregation}`