Basic access
Access control
Access to API endpoints requires credentials. This can be provided by means of:
- Cookies. When an API call is made from the browser while a user is logged in this can detect the user credentials from the provided cookie.
- Token. A per-user authorisation token can be provided in the
HTTP_AUTHORIZATIONheader when making an API call.
Cookies and access token are created, managed and validated by the content platform.
API endpoints
The API is located at this base URL:
Note
Examples in this documentation replaces the above base URL with <base> for brevity.
All queries are assembled from the base URL by providing additional product, path and query parameters. Fully assembled API endpoints follow this structure:
Path parameter: product
Required to determine which dataset to query against.
product |
Description |
|---|---|
stream |
Radio streaming analytics |
podcast |
Podcast access analytics |
account |
Account lifetime totals |
recognition |
Music recognition results |
Path parameter: type
Required to specify the desired result type. Currently queries support only one result type, but future iterations of this API allow for the same endpoint to return different results.
type |
Description |
|---|---|
totals |
A summary of data as one or more "rows". Most queries return this type. Typically used for data tables. |
timeseries |
A sequence of time-series values. Typically used for charting values over time. |
Path parameter: query
Required to specify which query to run. There are a wide range of query parameters available, each for grouping by a different dimension like country or hour of day.
Every query is documented with it's specific parameters and output data.
query group |
Available queries |
|---|---|
| Totals | metrics, top_providers, top_channels, top_episodes, top_streams, published (podcast), peaks (stream) |
| Behaviour | dropoff_rate, day_of_week, hour_of_day, day_and_hour, day_part |
| Geography | countries, regions, cities, geo_combined, unregion_combined, h3geopoints |
| Technology | devices, apps, platforms, referers, referer_domains, urlinfo, tech_combined |
| Timeseries | totals, published |
Future iterations of this API may implement additional queries based on business requirements.
Warning
Not all queries are available on all product and type combinations.
Query parameters
Every endpoint can be passed further required and optional values that are appended as HTTP URL query parameters. For example, the range parameter is required for all queries.
These are documented in the Query parameters section.