Required
API endpoints accept both required and optional parameters, appended as the HTTP URL query string.
These parameters allow filter, sort, group and adjust operations on the response data. Simple uses include pagination and timezone offset, while advanced combinations with multiple parameters and values are possible.
Required parameter list
| Parameter | Description |
|---|---|
range, from, to |
All queries must specify a reporting period via range.Optional from and to fields may be required. |
provider_id |
Required for stream or podcast queries against specific providers. |
stream_id |
Required for stream product queries against specific streams (stations). |
channel_id |
Required for podcast product queries against specific shows. |
episode_id |
Required for podcast product queries against specific episodes. |
ad_id |
Required for ad product queries. |
Reporting period
All analytics queries must specify a reporting period to query on. The range parameter is required, and can provide a prefix for frequently used time ranges or allow setting specific to and from dates.
| Relative ranges | Description |
|---|---|
this_month |
The current calendar month up to today. |
previous_month |
The previous calendar month. |
past_24_hours |
Past 24 hours, up to the last full hour. Query at 15:37 will return 24-hour period up to 15:00. |
last_7_days |
From yesterday 23:59 back 7 full days. Query on 15th of month will return inclusive values of 8th to 14th. |
last_30_days |
From yesterday 23:59 back 30 full days. Query on 31st of month will return inclusive values of 1th to 30th. |
campaign |
Only available for ad product. The duration of an ad campaign. |
| Absolute ranges | Description |
|---|---|
<ccyymm> |
A specific month, in ccyymm format, for example 202502 for February 2025. An easy way to get data for a specific calendar month. |
ccyymmdd |
Requires the to and from query parameters to specify the start and end dates as ccyy-mm-dd values, ex 2025-06-11. |
Note
Date ranges always return results inclusive of the last day.
A range of day 11 to 13 will return 3 days of data, including everything from the 13th.
Content identifiers
Every provider, stream, channel and episode stored in the dataset has a unique identifier, provided from the content platform. API results can be filtered by each of these.
| Content identifier | Description |
|---|---|
provider_id |
Shows results for a specific provider, can apply to stream and podcast product queries. Ex: africa_radio_sound or 2432. |
stream_id |
Shows results for a specific stream (station), available only for stream queries. |
channel_id |
Shows results for a specific podcast channel (show), available only for podcast queries. |
episode_id |
Shows results for a specific podcast episode, available only for podcast queries. |
Note
Multiple identifiers may be specified as a comma-seperated list to include multiple objects in one query.