Analytics API

The Analytics API provides daily aggregated listener session statistics for streams on the Radio Mast Streaming Network with Analytics enabled. Analytics data can be filtered by country, city, or player across a specified date range. Data is available as a time-series of daily datapoints or as an aggregate across a specified date range.

Getting Started

When browsing or querying the Analytics API, we recommend applying filters to get a more meaningful dataset. Click the Filters button in the top-right corner of the browseable API to apply filters.

As an example, to query listener sessions for US listeners only during May 2021, you would apply the following filters in the browseable API:

  • Station - Choose a station to query (or none for all stations)
  • Stream - Choose the stream to query (or none for all streams)
  • Timestamp - Enter 2021-05-01 to 2021-05-31
  • Breakdown 1 Dimension - Country
  • Breakdown 1 Filter - US
  • Breakdown 2 Dimension - None
  • Breakdown 2 Filter - ----- (Leave it unspecified)

Programmatically, to query listener session for US listeners during May 2021, make a GET request to /v1/analytics/listener-sessions/aggregate with the filters specified as querystring parameters:

curl -X GET -H "Authorization: Token <your-token>" https://api.radiomast.io/v1/analytics/listener-sessions/aggregate -d station="26dcdabf-9217-4a5d-9722-037da269fdc1" -d stream="6073c473-7930-4718-a174-ae03e6ea9550" -d timestamp_after="2021-05-01" -d timestamp_before="2021-05-31" -d breakdown_dimension="Country" -d breakdown_filter_by_value="US" -d breakdown2_dimension="null"

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "breakdown_dimension": "Country",
            "breakdown_filter_by_value": "US",
            "breakdown2_dimension": null,
            "breakdown2_filter_by_value": null,
            "listener_sessions": 228,
            "session_duration_avg": 1782,
            "session_duration_total": 407090
        }
    ]
}
import requests
import pprint

resp = requests.post("https://api.radiomast.io/v1/analytics/listener-sessions/aggregate", headers={'Authorization': "Token <your-token>"},
                     json={'station': '26dcdabf-9217-4a5d-9722-037da269fdc1',
                           'stream': '6073c473-7930-4718-a174-ae03e6ea9550',
                           'timestamp_after': '2021-05-01',
                           'timestamp_before': '2021-05-31',
                           'breakdown_dimension': 'Country',
                           'breakdown_filter_by_value': 'US',
                           'breakdown2_dimension': 'null'})
pprint.pprint(resp.json())

{
    'count': 1,
    'next': null,
    'previous': null,
    'results': [
        {
            'breakdown_dimension': 'Country',
            'breakdown_filter_by_value': 'US',
            'breakdown2_dimension': null,
            'breakdown2_filter_by_value': null,
            'listener_sessions': 228,
            'session_duration_avg': 1782,
            'session_duration_total': 407090
        }
    ]
}


Note that in this example, only a single data series is returned because we have filtered the data to US listeners only using breakdown_dimension and breakdown_filter_by_value.

Analytics API Reference

Listener Session Time Series API

https://api.radiomast.io/v1/analytics/listener-sessions/time-series

The Listener Session Time Series API provides daily listener session data across a specified time period. This API provides day-by-day data suitable for graphs.

Methods: GET

Parameters:

  • station - UUID of the radio station to filter by. Results are aggregated across all stations if null.
  • stream - UUID of the radio stream to filter by. Results are aggregated across all streams if null.
  • timestamp_after - Start of the date range to filter by. Format is YYYY-MM-DD, eg. 2021-05-01.
  • timestamp_before - End of the date range to filter by. Format is YYYY-MM-DD, eg. 2021-05-31.
  • breakdown_dimension - Name of the dimension to breakdown the statistics by. Valid values are: Country, City, or Player.
  • breakdown_filter_by_value - A specific value to filter the dimensional breakdown by, to only look at stats for one specific value. Possible values depend on the breakdown_dimension. For Country, valid values are ISO 3166-1 2 letter country codes. For City and Player, inspect the values in the Analytics web interface. Set to null or omit to get results for each possible value of the dimension (eg. data for each country).
  • breakdown2_dimension - Same as breakdown_dimension, but used to drilldown into the data. Both breakdown_dimension and breakdown_filter_by_value must be specified if this parameter is included. Set to null or omit if not needed.
  • breakdown2_filter_by_value - Same as breakdown_filter_by_value, but applying a filter to the second level breakdown. Set to null or omit if not needed.

Results:

This API returns a list of data corresponding to a time-series of the filtered Analytics data. For each breakdown value, there will be a result each day. The main data in each row returned is:

  • listener_sessions - The number of individual listener connections
  • session_duration_avg - The average listener session duration, in seconds. Note that this average is not available for the "Other" aggregation and will be zero. Read more about Other aggregations here.
  • session_duration_total - The sum of the duration of all listener sessions, in seconds. To get TLH (total listener hours) or ATH (aggregate tuning hours), divide by 3600.

Listener Session Aggregate API

https://api.radiomast.io/v1/analytics/listener-sessions/aggregate

The Listener Session Aggregate API provides daily listener session data aggregated across a specified time period. This API provides filtered totals and averages across the date range, more suitable for display in a table.

Methods: GET

Parameters:

See the parameters for the Listener Session Time Series API.

Results:

This API returns a list of data aggregated over the time range, for the filtered Analytics data. For each breakdown value, there will be a single result aggregated over the specified time span. If breakdown_dimension and breakdown_filter_by_value are explicitly null, the results will be totals for the specified station or stream.

FAQ

What's the difference between Time Series and Aggregate APIs?

Time series data has one datapoint per day per series within the date range. The aggregate API returns a single datapoint per series for the entire date range, which contains aggregated data (totaled or averaged).

The number of data series returned is determined by the filters applied.

For a demo of how each API could be used, view the "Listener Sessions" tab of the Analytics page inside your account. The graphs use data from the Listener Session Time Series API. The summary table below the graphs use data from the Listener Session Aggregate API.

What's the easiest way to get started?

We recommend playing with the Analytics API in your browser and trying to apply some filters. You can use this interface to build GET requests in your browser and see how the results change as you apply different filters.