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.
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:
2021-05-01 to 2021-05-31CountryUSNone----- (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.
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.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.
https://api.radiomast.io/v1/analytics/reports
The Reports API provides access to SoundExchange, BMI Music Use Reports, Re:Sound, ASCAP, and CPB-style reports. Reports are available quarterly or monthly, depending on the report type.
This API is asynchronous. Your first request will queue the generation of the report, and additional requests can be used to poll the status of the report and ultimately retrieve the download URL for the report.
Methods: POST, GET
Parameters:
station - UUID of the radio station to generate a report on. Required.stream - UUID of the radio stream to generate a report on. Results are aggregated across all streams if null.report_type - The type of report to generate. Valid types are: ascap, bmi_musicusereport, soundexchange, resound, cpbyear - The year of the reporting period.month_or_quarter - The month or quarter of the reporting period. Whether a month or quarter is specified
based on the report_type. For quarterly reports, specify q1, q2, q3, or q4.
For monthly reports, specify the number of the month (in the range 1 - 12).
Quarterly reports: ascap and bmi_musicusereport
soundexchange, resound, cpbResults:
This API will return a JSON object with a list of fields representing the report, including:
uuid - The unique identifier for the reportstatus - The current status of the report generation job. Status will be pending when the report is in progress
and success when the report is available. download_url - The download link where the report can be obtained. Only available once the status is success.date_created - The timestamp of when the report was requested.The station, stream, year, month_or_quarter, and report_type fields are also returned and correspond to the
same values as when the report was created.
Request an ASCAP report for 2022 Q1:
curl -X POST -H "Authorization: Token <your API key>" https://api.radiomast.io/v1/analytics/reports/ -d station=d30e4c77-6631-4697-99c6-278f9cff4635 -d report_type=ascap -d month_or_quarter=q1 -d year=2022
{
"uuid": "dd589ba5-1bec-4b89-a725-60f74fd09764",
"stream": null,
"station": "d30e4c77-6631-4697-99c6-278f9cff4635",
"date_created": "2022-09-06T20:50:29.043707Z",
"year": 2022,
"month_or_quarter": "q1",
"report_type": "ascap",
"status": "pending",
"download_url": ""
}
Check the status of this report or retrieve the download link:
curl -X GET -H "Authorization: Token <your API key>" https://api.radiomast.io/v1/analytics/reports/
{
"uuid": "dd589ba5-1bec-4b89-a725-60f74fd09764",
"stream": null,
"station": "d30e4c77-6631-4697-99c6-278f9cff4635",
"date_created": "2022-09-06T20:50:29.043707Z",
"year": 2022,
"month_or_quarter": "q1",
"report_type": "ascap",
"status": "success",
"download_url": "https://nyc3.digitaloceanspaces.com/radiomast-reports/1/dd589ba5-1bec-4b89-a725-60f74fd09764.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=JQ33I2P3HUC64BZANL4K%2F20220906%2Fnyc3%2Fs3%2Faws4_request&X-Amz-Date=20220906T205146Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=ea5a6c707c47d98a98d17f0bf762a72f03ac67c501d12537cd299373e1e5d789"
}
Downloading the report:
# We recommend using wget with the --content-disposition header if you would like the report's filename
# to preserved.
wget --content-disposition "https://nyc3.digitaloceanspaces.com/radiomast-reports/1/dd589ba5-1bec-4b89-a725-60f74fd09764.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=JQ33I2P3HUC64BZANL4K%2F20220906%2Fnyc3%2Fs3%2Faws4_request&X-Amz-Date=20220906T205146Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=ea5a6c707c47d98a98d17f0bf762a72f03ac67c501d12537cd299373e1e5d789"
2022-09-07 13:37:05 (0.00 B/s) - ‘ascap_2022_q1.txt’ saved [0/0]
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.
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.