Get radios
Get a list of radios filtered by attributes and stats.
You can sort radios in our database using specific parameters such as platform, metric type, or time period, and filter them based on attributes like radio country, radio genres, track age or performance metrics.
These are the available platfom/metricType combinations for the radio audience:
- reach: soundcharts
- subscribers: youtube
- followers: instagram, tiktok, twitter
- likes: facebook
Sort
| Name | Value | Description | Additional |
|---|---|---|---|
| Sort | object | Sort radios by a metric (by total or change over a period) | Optional |
| platform | string | Code of the platform used for sorting metric. Find out the available platform in the description above. |
Required |
| metricType | string | Type of metric used for sorting the radios. Find out the available metricType per platform in the tabs above. |
Required |
| sortBy | string | Sort the list of radios by either: - The latest total value - Absolute gain/loss over a time period - Relative gain/loss (in percent) over a time period Available values: total, volume, percent | Required |
| period | string | Time period used in the sorting. Available values: week, month, quarter |
Required |
| order | string | Available values: desc, asc | Required |
Filters
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | metric Filter radios by any metric |
Required |
| data | object | Required | |
| data.platform | string | Code of the platform used for the filtering metric. Find out the available platform in the description above. |
Required |
| data.metricType | string | Type of metric used for filtering the radios. Find out the available metricType per platform in the tabs above. |
Required |
| data.min | float | Set the minimum value for filtering. - Enter a number to filter by total value or growth. - Enter a percentage to filter by percentage growth. |
At least one of min or max is mandatory |
| data.max | float | Set the max value for filtering. - Enter a number to filter by total value or growth. - Enter a percentage to filter by percentage growth. |
At least one of min or max is mandatory |
| data.period | string | Specify the time period for filtering when changeType is volume or percent. Available values: week, month, quarter |
Optional |
| data.changeType | string | Choose the type of audience filtering: volume or percent. - Set "volume" to filter by growth over the time period defined in the period field. - Set "percent" to filter by percentage growth over the defined time period. - Leave blank or omit this field to filter by total value. | Optional |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | radioCountryCode Filter radios by their country |
Required |
| data | object | Required | |
| data.values | array of strings | A list of 2 letters ISO 3166-2 country codes. Example: 'US', 'UK' Full list on https://en.wikipedia.org/wiki/ISO_3166-2 |
Required |
| data.operator | string | in: Select radios where at least one country matches any of the specified options. not_in: Exclude radios where at least one country matches any of the specified options. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | radioGenres Filter radios by genres |
Required |
| data | object | Required | |
| data.values | array of strings | A list of radio genres. Find out the available list Get song genres endpoint. |
Required |
| data.operator | string | in: Select radios who have at least one of the specified genres. not_in: Exclude radios who have at least one of the specified genres. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | trackAge Filter radios by type |
Required |
| data | object | Required | |
| data.values | array of strings | A list of track age. Available values: catalog, mixed, frontline |
Required |
| data.operator | string | in: Select radios whose type matches any of the specified options. not_in: Exclude radios whose type matches any of the specified options. |
Required |
Request
POST /api/v2/top/radios
Query string parameters
| Parameter name | Value | Description | Additional |
|---|---|---|---|
| offset | integer | Get results starting from position |
|
| limit | integer | Number of results (max. 100) |
Body parameters
| Parameter name | Value | Description | Additional |
|---|---|---|---|
| body | JSON Payload |
Required |
Response
| Status code | Description | Resource |
|---|---|---|
| 200 | OK
Top radio collection response |
TopRadioCollectionResponse |
| 400 | Bad Request
Invalid request |
|
| 401 | Unauthorized
You are not logged in |
|
| 403 | Forbidden
This endpoint is not included in your current plan, reach out to help@soundcharts.com if you want access. |