Return recommendations for radio stations
/recommendations
Retrieves recommendations of stations and (optionally) on-demand items if the onDemand
parameter is supplied.
The country
parameter is compulsory here, to set which country the recommendations come from.
Results can be further tailored by the use of the mandatory factors
parameter. factors
makes use of additional supplied data given in other parameters.
This includes:
GEO
– recommendations are influenced bylatitude
andlongitude
parameters where these are present in the POST request. To improve performance, latitude and longitude values should be precise to no more than two decimal places (accuracy to within around 1km)TRENDING
– recommendations are influenced by stations gaining in current popularity. It does not require additional parameters other thancountry
to be supplied.AFFINITY
– recommendations are influenced by anrpuid
where this is supplied, leading to greater weight towards stations with similar content.MUSICMATCH
– recommended results are influenced byartistPlayCounts
and/orfacebookArtists
parameters where these are supplied in the POST request.
This endpoint is the sole POST operation in the WRAPI. This means, in order to receive more meaningful results, data such as the current geolocation, existing social media preferences, etc must be posted to the WRAPI in the form of parameters to be used in its calculations.
Endpoint
https://api.radioplayer.org/v2/recommendations Method: POST
Request parameters
Header Fields
To find out how to correctly construct authentication headers for the Radioplayer Partner API (WRAPI) please see the Authentication guide.
Query Parameter
Get recommendations for a country
/v2/stations/?country=826
Post snippet for AFFINITY as a factor
"factors": [
"AFFINITY"
],
"rpuid":826347
Post snippet of factors
"factors": [
"GEO",
"TRENDING",
"AFFINITY",
"ONDEMAND",
"MUSICMATCH"
]
Post snippet of latitude and longitude
"latitude": 51.52,
"longitude": 0.16
Post snippet facebook artists
"facebookArtists": [
"robbie williams",
"feist",
"david bowie"
]
Post snippet of artist play counts
"artistPlayCounts": [
{
"artistName": "blur",
"playCount": 20
},
{
"artistName": "feist",
"playCount": 10
}
]
Post snippet to include On Demand items
{
"rpuid": "826100",
"country": "826",
"factors": ["GEO"],
"onDemand": true
}
Full Sample POST Response Body
{
"latitude": 51.521129,
"longitude": 0.16768,
"factors": [
"GEO",
"TRENDING",
"AFFINITY",
"ONDEMAND",
"MUSICMATCH"
],
"rpuId": 826347,
"artistPlayCounts": [{
"artistName": "blur",
"playCount": 20
},
{
"artistName": "feist",
"playCount": 10
}
],
"facebookArtists": [
"robbie williams",
"feist",
"david bowie"
]
}
QUERY PARAMETER | VALUE |
---|---|
country |
GET, Required. An ISO 3166 numeric country code. When applied only returns results from the specified country. Recommended parameter. |
rpuid |
POST, Required. if using AFFINITY value in factors parameter. Optional otherwise. Unique identifier for a station object.This can be used to inform recommendations for similar radio stations, based on the station supplied by the rpuid. To do this, supply the AFFINITY value for the factors parameter as well as rpuid . |
factors |
POST, Required. This parameter controls which mechanism will be used to generate recommendations. There are four options: AFFINITY - influences returned recommendation results based upon an rpuid supplied in the POST request.GEO - influences recommendations based upon geographical locations. Requires both longitude and latitude to be supplied in the POST request.TRENDING - influences recommendations based upon radio stations experiencing a surge in popularity. Does not require addtional parameters apart from mandatory country parameter.MUSICMATCH - influences recommendations based upon social media criteria supplied by the individual, as returned by the facebookArtists and artistPlayCounts parameters. |
latitiude |
POST, Required if using GEO value in factors parameter, where it also requires longitude . Optional otherwise.Returns station objects matching a specified geolocation value in latitude and longitude. |
longitude |
POST, Required if using GEO value in factors parameter, where it also requires latitiude . Optional otherwise.Returns station objects matching a specified geolocation value in latitude and longitude. |
facebookArtists |
POST, Required if using MUSICMATCH value in factors parameter, unless the artistPlayCounts is used instead. Optional otherwiseAn array of artist names that used in conjunction with the MUSICMATCH parameter can help tailor recommendations. |
artistPlayCounts |
POST, Required if using MUSICMATCH value in factors parameter, unless the facebookArtists is used instead. Optional otherwiseAs array of objects each containing an artistName string, and a corresponding playCount integer. Used in conjunction with the MUSICMATCH parameter. |
onDemand |
POST, Optional, Boolean. Flag that when set to true determines whether on-demand content should be returned amongst live radio recommendations. |
Response
When successful, the HTTP status code in the response header is 200 OK. One or more station objects are returned in JSON format (or on special request, XML supported by the RadioDNS schema).
content-type: application/json; charset=utf-8
x-ratelimit-limit: 300000
x-ratelimit-remaining: 285030
x-ratelimit-reset: 1585699200
If there is an error, the header returns an error status code. error status code.
The WRAPI also includes information about your monthly request quota in the returned header:
This includes information on:
Your total monthly quota
How many requests you have remaining for the month
When the quota will be reset, given as a UNIX timestamp.
Example Response Body
{
"data": [
{
"name": "Absolute 80s",
"description": "The UK's 80s radio station.",
"liveStreams": [
{
"streamSource": {
"url": "http://ais.absoluteradio.co.uk/absolute80s.aac?direct=true",
"mimeValue": "audio/aac"
},
"bitRate": {
"target": 24000
},
"streamRestriction": {
"value": "826",
"relationship": "allow"
}
},
{
"streamSource": {
"url": "https://ais.absoluteradio.co.uk/absolute80shigh.aac?direct=true",
"mimeValue": "audio/aac"
},
"bitRate": {
"target": 64000
},
"streamRestriction": {
"value": "826",
"relationship": "allow"
}
}
],
"epgLanguages": [
"en"
],
"alphanumericKey": "a",
"multimedia": [
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_600x600_2018-11-28-02-45-11-97.png",
"mimeValue": "image/png",
"language": "en",
"width": 600,
"height": 600
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_86x48_2019-10-23-16-30-12-423.png",
"mimeValue": "image/png",
"language": "en",
"width": 86,
"height": 48
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_288x162_2019-10-23-16-30-12-557.png",
"mimeValue": "image/png",
"language": "en",
"width": 288,
"height": 162
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_128x128_2018-11-28-02-45-11-517.png",
"mimeValue": "image/png",
"language": "en",
"width": 128,
"height": 128
},
{
"url": "http://ukrpimagecache.s3.amazonaws.com/image/101_74x41_2013-11-11-17-01-55-343.png",
"mimeValue": "image/png",
"language": "en",
"width": 74,
"height": 41
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_160x90_2019-10-23-16-30-12-943.png",
"mimeValue": "image/png",
"language": "en",
"width": 160,
"height": 90
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_320x240_2018-11-28-02-45-11-812.png",
"mimeValue": "image/png",
"language": "en",
"width": 320,
"height": 240
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_112x32_2018-11-28-02-45-12-501.png",
"mimeValue": "image/png",
"language": "en",
"width": 112,
"height": 32
},
{
"url": "https://ukrpimagecache.s3.amazonaws.com/image/101_32x32_2018-11-28-02-45-12-855.png",
"mimeValue": "image/png",
"language": "en",
"width": 32,
"height": 32
}
],
"country": "826",
"rpuid": "826101",
"bearers": [
{
"id": "dab:ce1.c1a6.c8d8.0",
"cost": 0,
"mimeValue": "audio/mpeg"
},
{
"id": "dab:ce1.c1ce.c8d8.0",
"cost": 0,
"mimeValue": "audio/mpeg"
}
],
"phoneticInputs": [
{
"id": "1510139248909_1415_i",
"type": "pidgin",
"value": "absolute radio eighties",
"exclude": []
},
{
"id": "1510139248903_217_i",
"type": "pidgin",
"value": "absolute eighties",
"exclude": []
}
],
"phoneticOutputs": [
{
"id": "1510139248903_218_o",
"type": "pidgin",
"value": "absolute eighties",
"exclude": []
}
],
"type": "STATION",
"factors": [
"AFFINITY"
]
},
...
],
"meta": {
"nesting": false,
"paginated": false,
"dataType": "recommendations",
"count": 16,
"fromCache": false,
"cacheExpiresAt": 1585411241315
}
}
The returned response body consists of a meta
and data
object.
The possible meta
field values for this endpoint are:
FIELD | VALUE |
---|---|
paginated |
Optional, Boolean. Sets how or if results are grouped into pages. For more information on pagination, see the API Documentation index. |
nesting |
Optional, Boolean. Indicates whether full data objects are nested within other objects. For more information on nesting, see the API Documentation index. |
dataType |
Object type returned by the request. In this case it is recommendations . |
count |
Optional, string. A number describing how many items are in the data set. |
fromCache |
Optional, Boolean. Indicates whether this data came from cached data. This will always be fals as POST results cannot be cached. For more information on caching, please see the API Documentation index. |
cacheExpiresAt |
Optional. UNIX timestamp indicating when the cache will expire. POST data is not cached For more information on caching, please see the API Documentation index. |