Radioplayer Developer Reference
Best Practices for Data API Usage
Technical reference for Radioplayer partner integrations.
- Version
- Current
- Document type
- API reference
- Audience
- Radioplayer partner engineering teams
Common query parameters
Lists / multiple values
- When a parameter supports multiple values, pass a comma-separated list:
A,B,C
In URLs you’ll often see this encoded as %2C.
Date range
- start_date , end_date :
YYYY-MM-DD
The interval is inclusive.
Time resolution
- granularity :
HOUR or DAY
Changes how metrics are interpreted (e.g., listeners per day vs per hour).
Aggregation keys
- group_by : defines how the output is aggregated (supported values depend on endpoint).
Station selection
- rpuid or radio_name : one or more stations.
Recommended: rpuid (less error-prone than names). Example: 380102 (Italy 380 + station id).
Device category
category (one or more):
- Automotive, ConnectedTV, SmartPhone, Wearables, Web, Others, Speakers, SmartSpeakers, Pc & Tablet
_(Note:_Pc & Tablet _must be URL-encoded as_Pc%20%26%20Tablet _)_
Geography
- geo_country : the _physical_ geo location of the session
- city: the physical city of the session
- country_code : the _catalog country_ selected by the user
Timezone handling
Session duration filter
- min_session_duration :
0, 15, 30, 60 seconds
_Ignored for USERS metric._
Publisher scoping
- publisher_id : broadcaster group ID (if empty, station subset is based on account key)
Examples: Sessions
1) Listening sessions per day (default min_session_duration = 60s)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=day_param&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
2) Listening sessions per day with min_session_duration = 15s
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=day_param&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false&min_session_duration=15' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
3) Listening sessions per day in local timezone
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=day_param&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=true' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Date-part sessions (hour/week-part)
4) Sum of sessions per hour in local timezone
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/date_part/sessions?start_date=2026-01-01&end_date=2026-01-11&granularity=HOUR&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&local_timezone=true&min_session_duration=60' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
5) Sessions per week part split by hours
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/date_part/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=week_part&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&local_timezone=true&min_session_duration=60' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Users (listeners)
6) Listeners per day
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/users?start_date=2026-01-01&end_date=2026-01-11&group_by=day_param&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
7) Listeners per day for two stations (RPUID filter)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/users?start_date=2026-01-01&end_date=2026-01-11&group_by=day_param&rpuid=380102%2C380101&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Sessions by day-of-week
8) Listening sessions per day name (Mon/Tue/…)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=dayname_param&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Category breakdown
9) Sessions by category + sub_category
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-11&group_by=category%2Csub_category&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Geo filtering (catalog country vs geo_country)
10) Sessions of Germany catalog users located in Italy
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/sessions?start_date=2026-01-01&end_date=2026-01-05&group_by=day_param&country_code=276&geo_country=Italy&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&week_aggregation=false&local_timezone=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Aggregations (period totals)
11) Reach: distinct listeners in a period
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/aggregations/reach?start_date=2026-01-01&end_date=2026-01-10&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&local_timezone=false&min_session_duration=60' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
12) Audience: number of sessions in a period
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/aggregations/audience?start_date=2026-01-01&end_date=2026-01-10&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&local_timezone=false&min_session_duration=60' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
13) Total TSL: total time spent listening (minutes) in a period
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/aggregations/total_tsl?start_date=2026-01-01&end_date=2026-01-11&category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&local_timezone=false&min_session_duration=60' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Music analytics
14) Most listened-to artists in a period
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/music/sessions?start_date=2025-12-01&end_date=2025-12-31&group_by=artist' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
15) Most listened-to songs in a period (song_title + artist)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/music/sessions?start_date=2025-12-01&end_date=2025-12-31&group_by=song_title%2Cartist' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Examples: Programmes analytics
16) Most listened-to programmes in a period (Italy example)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/programmes/sessions?start_date=2025-12-01&end_date=2025-12-31&group_by=program_title%2Crpuid&country_code=380' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
17) On-demand listening sessions per day per podcast (Italy example)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/ondemand/sessions?start_date=2026-01-01&end_date=2026-01-01&country_code=380&group_by=day_param%2C%20podcast_title&device_category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&limit=1000' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Parameters
18) Podcast Subscriptions (Italy example)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/ondemand/sessions?start_date=2026-01-01&end_date=2026-01-01&country_code=380&group_by=day_param%2C%20podcast_title&device_category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&limit=1000' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Parameters
19) Station Subscriptions Chart (new favourites - churns) (Italy example)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/user_journey/station_subscriptions?start_date=2026-01-01&end_date=2026-01-13&country_code=380&group_by=rpuid%2C%20radio_name&device_category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&limit=1000' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Parameters
20) Station Subscriptions per day (Italy example)
curl -X 'GET' \
'https://data-api.radioplayer.cloud/dev/analytics/v2/user_journey/station_subscriptions?start_date=2026-01-01&end_date=2026-01-13&country_code=380&group_by=day_param&device_category=Automotive%2CConnectedTV%2CSmartPhone%2CWearables%2CWeb%2COthers%2CSpeakers%2CSmartSpeakers%2CPc%20%26%20Tablet&limit=1000' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <REDACTED>'
Parameters