Analytics

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

ComponentPassed asDescription
Data Set
required
URL parameterData range to be aggregated.
Currently supports:
  1. trends (consumption)
  2. revenue
Aggregation Dimension
required
URL parameterData grouping dimension.
Currently supports:
  1. byCountry
  2. byDistributor
  3. byTrack
  4. byDeliveryType
Date Granularity
optional
Querystring parameter: dateGranularityFilter Level of date grouping.
Options are:
  1. Daily
  2. Monthly
  3. Yearly
  4. All
  5. null to not aggregate by date
Filter
optional
Querystring parameters:
  1. releaseId
  2. trackId
  3. artistId
  4. labelId
  5. 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:
  1. pageSize
  2. pageNumber
Controls the amount of response data provided.
Order
optional
Querystring parameters:
  1. orderByDescending (boolean)
  2. 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&token=c1234562-5f45-4ab6-b6fb-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&token=c1234562-5f45-4ab6-b6fb-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

ParameterTypeDescription
fromDate
optional
stringThe 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
stringThe 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
stringDefaults 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

ParameterTypeDescription
fromDate
optional
stringThe 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
stringThe 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
stringDefaults 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 --header 'Accept: text/plain'\ 
'https://api.revelator.com/analytics/trends/metricsByDate/?fromDate=2021-11-02&toDate=2021-11-05&metrics=totalStreams'
Request
curl -X GET --header 'Accept: text/plain'\ 
'https://api.revelator.com/analytics/revenue/metricsByDate/?fromDate=2021-11-02&toDate=2021-12-09&metrics=totalRevenue&metrics=dayRevenueQuantity'