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.

API Reference