API Reference

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 by latitude and longitude 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 than country to be supplied.

  • AFFINITY – recommendations are influenced by an rpuid where this is supplied, leading to greater weight towards stations with similar content.

  • MUSICMATCH – recommended results are influenced by artistPlayCounts and/or facebookArtists 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 otherwise

An 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 otherwise

As 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.