Radioplayer Developer Reference

WRAPI v3

Technical reference for Radioplayer partner integrations.

Version: Current
Document type: API reference
Audience: Radioplayer partner engineering teams

WRAPI v3 Endpoints
- /WRAPI/v3/recommendations
- WRAPI/v3/stations
- WRAPI/v3/ondemand

WRAPI v3 Endpoints

/WRAPI/v3/recommendations

Description

This endpoint allows users to request recommended radio stations and on-demand content based on various factors such as user location, listening behavior, and content popularity. The results are filtered based on the client's access permissions and the provided country code.

Request Parameters

The request consists of:

Query Parameters _(sent in the URL query string)_
Headers _(metadata sent in the HTTP request headers)_
Body Parameters _(sent in the request payload as JSON)_

Query Parameters

Name	Type	Required	Description
`country`	`string`	Yes	The country code used to filter results. This parameter is required and should be passed in the URL query string.

Example Request (Query Parameters)

POST /WRAPI/v3/recommendations?country=380

Request HeadersName| Type| Required| Description

---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. This must be provided in the request headers. The response will be filtered to include only content that the client has access to.

Example Request with Header

POST /WRAPI/v3/recommendations?country=380
Content-Type: application/json
Radioplayer-Client: client@radioplayer.org

Body ParametersName| Type| Required| Description

---|---|---|--- country| string| No| The country code used to filter results. If also provided in the query parameters, the query parameter value takes precedence. latitude| float| No| The latitude of the user's location (used for GEO-based recommendations). longitude| float| No| The longitude of the user's location (used for GEO-based recommendations). factors| array| No| A list of recommendation factors to apply. If not specified, an empty list is used. Allowed values: GEO, TRENDING, AFFINITY, ONDEMAND, MUSICMATCH. rpuid| string| No| The station ID currently being listened to. Used for affinity-based recommendations. artistPlayCounts| array| No| A list of artists and their play counts. Currently, this parameter is not used to generate recommendations. facebookArtists| array| No| A list of Facebook artists associated with the user. Currently, this parameter is not used to generate recommendations. onDemand| boolean| No| If true, the ONDEMAND factor will be included automatically. Default:false. disablePV| boolean| No| If true, PUBLICVALUE-based filtering for Germany will be disabled. Default:false.

Sample request body

{
    "country": "string",
    "latitude": 0,
    "longitude": 0,
    "factors": [
    "string"
    ],
    "rpuid": "string",
    "artistPlayCounts": [
    {
        "artistName": "string",
        "playCount": 0
    }
    ],
    "facebookArtists": [
    "string"
    ],
    "onDemand": false,
    "disablePV": false
}

Response Format

The response consists of a list of recommended radio stations and on-demand content , including details about the recommendation factors used. The results are filtered based on the client's access permissions and the provided country code.

Sample Response

"data": [
{
    "name": "string",
    "description": "string",
    "alphanumericKey": "string",
    "liveStreams": [
    {
        "streamSource": {
            "url": "string",
            "mimeValue": "string"
        },
        "audioFormat": "string",
        "bitRate": {
            "target": 0,
            "variable": false
        }
    }
    ],
    "genres": [
    {
        "href": "string",
        "name": "string",
        "type": "string"
    }
    ],
    "socialIds": [
    {
        "type": "string",
        "uid": "string"
    }
    ],
    "multimedia": [
    {
        "type": "string",
        "url": "string",
        "width": 0,
        "height": 0,
        "language": "string",
        "mimeValue": "string",
        "index": 0
    }
    ],
    "country": "string",
    "rpuid": "string",
    "bearers": [
    {
        "id": "string",
        "cost": 0,
        "mimeValue": "string"
    }
    ],
    "phoneticInputs": [
    {
        "id": "string",
        "type": "string",
        "value": "string",
        "exclude": [
        "string"
        ]
    }
    ],
    "phoneticOutputs": [
    {
        "id": "string",
        "type": "string",
        "value": "string",
        "exclude": [
        "string"
        ]
    }
    ],
    "shortNames": [
    {
        "value": "string",
        "language": "string"
    }
    ],
    "mediumNames": [
    {
        "value": "string",
        "language": "string"
    }
    ],
    "longNames": [
    {
        "value": "string",
        "language": "string"
    }
    ],
    "type": "string",
    "factors": [],
    "keywords": []
},
{
    "id": "string",
    "type": "string",
    "name": "string",
    "description": "string",
    "alphanumericKey": "string",
    "country": "string",
    "rpuid": "string",
    "factors": [],
    "longDescriptions": [],
    "onDemandStreams": [],
    "genres": [],
    "series": [],
    "multimedia": [],
    "mediumNames": [
    {
        "value": "string",
        "language": "string"
    }
    ],
    "longNames": [
    {
        "value": "string",
        "language": "string"
    }
    ],
    "keywords": [
    {
        "value": "string",
        "language": "string"
    }
    ]
}
],
"meta": {
    "nesting": true,
    "paginated": true,
    "dataType": "string",
    "count": 0,
    "fromCache": true,
    "cacheExpiresAt": 0
}
}

Notes

Query Parameter country is mandatory and should be passed in the URL query string.
Header Parameter client_id is mandatory and must be included in the request headers.
Body Parameters should be sent as a JSON object.
country can also be passed in the request body, but if it is present in both the query parameters and the body, the value from the query parameter takes precedence.
If onDemand is set to true, the ONDEMAND factor will be included automatically even if not specified in factors. Default:false.
If no factors are specified , an empty list is used, leading to no recommendations.
If disablePV is false and the request is made for Germany (countryCode = 276) , station recommendations will be based exclusively on PUBLICVALUE), ignoring other factors. Default:false.
The results provided are filtered based on the client's access permissions and the country code specified in the request.
artistPlayCounts andfacebookArtists parameters arecurrently not used to generate recommendations.

WRAPI/v3/stations

Description

This endpoint allows users to search for live radio stations based on a query term, country code, and additional filters. Results are filtered based on the client's access permissions and the provided country code.

Request Parameters

The request consists of:

Query Parameters _(sent in the URL query string)_
Headers _(metadata sent in the HTTP request headers)_

Query ParametersName| Type| Required| Description

---|---|---|--- search| string| No| The user-provided search terms. If not specified, the response will return random results filtered by country. include| string| No| Specifies which fields are returned for each station object (comma-separated). Available values: ids, detail, bearers, social, streams, images. If not provided, all fields will be returned. country| string| Yes| The country code used to filter results. This parameter is required. bearerId| string| No| The bearer ID associated with a station. Note: This parameter is accepted but not used to process the response. geo| string| No| Latitude and longitude (format: lat,lon) used to enable geo-location-based station recommendations. sort| string| No| Sorts returned results into alphanumeric order. Case-insensitive. Note: This parameter is accepted but not used to process the response.

Example Request (Query Parameters)

GET /WRAPI/v3/stations?country=380&search=rock&include=detail,streams

Request HeadersName| Type| Required| Description

---|---|---|--- Radioplayer-Client| string| Yes| A unique identifier for the client making the request. This must be provided in the request headers. The response will be filtered to include only content that the client ha access to.

Example Request with Header

GET /WRAPI/v3/stations?country=380&search=rock
Content-Type: application/json
Radioplayer-Client: client@radioplayer.org

Response Format

The response consists of a list of radio stations that match the provided search terms and filters, including metadata and streaming details.

Sample Response

{
    "data": [
    {
        "name": "string",
        "description": "string",
        "alphanumericKey": "string",
        "liveStreams": [
        {
            "streamSource": {
                "url": "string",
                "mimeValue": "string"
            },
            "audioFormat": "string",
            "bitRate": {
                "target": 0,
                "variable": false
            }
        }
        ],
        "genres": [
        {
            "href": "string",
            "name": "string",
            "type": "string"
        }
        ],
        "socialIds": [
        {
            "type": "string",
            "uid": "string"
        }
        ],
        "multimedia": [
        {
            "type": "string",
            "url": "string",
            "width": 0,
            "height": 0,
            "language": "string",
            "mimeValue": "string",
            "index": 0
        }
        ],
        "country": "string",
        "rpuid": "string",
        "bearers": [
        {
            "id": "string",
            "cost": 0,
            "mimeValue": "string"
        }
        ],
        "phoneticInputs": [
        {
            "id": "string",
            "type": "string",
            "value": "string",
            "exclude": [
            "string"
            ]
        }
        ],
        "phoneticOutputs": [
        {
            "id": "string",
            "type": "string",
            "value": "string",
            "exclude": [
            "string"
            ]
        }
        ]
    }
    ],
    "meta": {
        "nesting": true,
        "paginated": true,
        "dataType": "string",
        "count": 0,
        "fromCache": true,
        "cacheExpiresAt": 0
    }
}

Notes

Query Parameter country is mandatory and must be provided in the request.
Header Parameter client_id is mandatory and must be included in the request headers.
If searchis not provided , the API returns random results filtered by country.
If includeis not specified , all fields are returned by default.
The geo parameter must be in lat,lon format to enable location-based recommendations.
Results are filtered based on the client's access permissions and the country code specified in the request.
Sorting (sort) applies alphanumeric ordering but is not used to process the response.
ThebearerId parameter is accepted but does not impact the response.

WRAPI/v3/ondemand

Description

This endpoint allows users to search for on-demand audio content (e.g., podcasts, recorded shows) based on a query term, country code, and additional filters. Results are filtered based on the client's access permissions and the provided country code.

Request Parameters

The request consists of:

Query Parameters _(sent in the URL query string)_
Headers _(metadata sent in the HTTP request headers)_

Query ParametersName| Type| Required| Description

---|---|---|--- search| string| No| The user-provided search terms. If not specified, the response will return random results filtered by country. country| string| Yes| The country code used to filter results. This parameter is required. rpuids| string| No| A list of station RPUIDs used to filter results. Note: This parameter is accepted but not used to process the response. category| string| No| A category filter to narrow down results based on content type. Note: This parameter is accepted but not used to process the response.

Example Request (Query Parameters)

GET /WRAPI/v3/ondemand?country=826&search=history

2. Request HeadersName| Type| Required| Description

Example Request with Header

GET /WRAPI/v3/ondemand?country=826&search=history
Content-Type: application/json
Radioplayer-Client: client@radioplayer.org

Response Format

The response consists of a list of on-demand episodes that match the provided search terms and filters, including metadata and streaming details.

Sample Response

{
    "data": [
    {
        "id": "string",
        "name": "string",
        "description": "string",
        "longDescriptions": [],
        "onDemandStreams": [],
        "series": [],
        "multimedia": [
        {
            "type": "string",
            "url": "string",
            "width": 0,
            "height": 0,
            "language": "string",
            "mimeValue": "string",
            "index": 0
        }
        ],
        "alphanumericKey": "string",
        "mediumNames": [],
        "longNames": [],
        "country": "string",
        "rpuid": "string"
    }
    ],
    "meta": {
        "nesting": true,
        "paginated": true,
        "dataType": "string",
        "count": 0,
        "fromCache": true,
        "cacheExpiresAt": 0
    }
}

Notes

Query Parameter country is mandatory and must be provided in the request.
Header Parameter client_id is mandatory and must be included in the request headers.
If searchis not provided , the API returns random results filtered by country.
Results are filtered based on the client's access permissions and the country code specified in the request.
Therpuids parameter is accepted butdoes not impact the response.
Thecategory parameter is accepted butis not currently used to process the response.