API Reference

Overview

Welcome to the Radioplayer Partner API (WRAPI) documentation.

The Radioplayer Partner API (WRAPI) provides developers with unparalleled access to broadcasters' streaming radio programming and proprietary metadata. You can use this to build a rich and flexible hybrid radio experience for your customers.

Here you can find:

If you have any questions, please see our FAQs later on this page.

Base address and endpoints

The base address for the Radioplayer Partner API (WRAPI) is: api.radioplayer.org/v2/

There are ten endpoints to the Radioplayer Partner API (WRAPI):

Endpoint Purpose
/stations returns a list of all information on all stations, unless filtered by parameters. Also provides the ability to search for stations in a number of ways including keyword searching, search by bearers and search for local station
/stations/{rpuids} returns information on a particular station, identified by its rpuid.
/stations/{rpuids}/onair provides current “track now playing” information from one or multiple radio stations
/stations/{rpuids}/schedule returns programme schedules for up to five radio stations
/stations/{rpuid}/ondemand returns a list of on-demand items for a given radio station
/stations/{rpuid}/ondemand/{seriesId} returns a list of on-demand content for a given series
/ondemand returns details on all pieces of on-demand content, unless filtered by parameters
/ondemand/{odIds} returns all information on a particular piece of on-demand content, identified by its OD ID.
/recommendations shows recommended content based on station affinity, music preferences from social media such as facebook, geolocation and generally trending stations.
/categories returns information on all stations based on their content category, where this is available.

All of the results from these calls can be filtered and sorted using a set of query parameters.

Requests

The Radioplayer Partner API (WRAPI) is a "RESTful" API that responds to signed HTTPS requests. These are all GET operations, with the exception of the /recommendations endpoint that needs a POST request.

Each successfully authenticated request elicits data from the Radioplayer metadata service which can be cached in the middleware client and polled by your customers. Guidance is given here on the length of time such data should be cached.

Authentication

Every request sent to Radioplayer's metadata service needs to be authenticated by the Radioplayer Partner API (WRAPI), so each arrives in the form of a signed HTTPS request.

A guide to signing and securing your requests to the Radioplayer Partner API (WRAPI) is available here.

There is no persistence in this security – every request sent must be signed and authenticated, but it is possible to cache data in the middleware client.

Rate limiting

During your trial, you will be able to determine how many calls are required to build an application – and from there you should be able to project future usage. Upon agreement of a full licence, these metrics will be used to determine your monthly request quota (refreshed on the first day of each calendar month).

Radioplayer helps you manage your quota with:

  • Advice on optimal caching strategies for your data
  • Server-side usage tracking, with information on how many requests you have left, your quota, and how many you have used
  • Email reminders that you have used 80% of your quota and then when you have exhausted your quota.

To learn more, consult our API optimisation guide.

Responses

{
    "meta": {
    "paginated": false,
    "nesting": false
    "count": 270
    },

    "data": [
        { OBJECT },
        { OBJECT },
        ...
    ]
}

Successful requests result in responses in JSON format (or, on request, XML format supported by the RadioDNS schema).

All responses from the Radioplayer metadata service are structured in the same way. There is an envelope containing two objects:

  • A meta object that directs how the content is returned
  • A data array that describes the data that has been returned.

The meta object controls whether the results are:

  • nesting – whether data objects returned in the envelope contain other data objects, each with their own meta and data components.
  • paginated – whether data is returned in pages, which are sized groups.

The count value lists how many objects were returned in the data array.

Error codes in responses

The following error codes can be returned in the case of unsuccessful responses:

Error Code Meaning
400 An error in the request, such as an invalid country code
403 Authorization failure
404 Station doesn't exist
429 Monthly request quota has been used up

To learn more about monthly request quotas, please see Rate Limiting.

Nesting and pagination

{
"meta": {
    "paginated" : false,
    "nesting": true,
    "count": 2
},
"data": [
    {
    "meta": {
        "paginated": false,
        "nesting": false,
        "count": 2
    },
    "data": [
        {OBJECT},
        ...
    ]
    },
    { ... }
]
}

If you are returning objects with multiple parents, such as on-demand shows that correlate to a search term (where there are multiple stations each with multiple on-demand shows), this will require a nesting structure.

{ 
    "meta": { 
    "paginated": false, 
    "nesting": false, 
    "count": 276, 
    "pageSize": 10, 
    "firstPage": true, 
    "lastPage": false, 
    "totalPages": 77, 
    "pageNumber": 0 
    }, 
    "data": [ 
    {
        

In this case the structure of the response will look slightly different. The first sample on the right shows the response when the nesting flag in meta has been set to true.

In the case of pagination, if this is set to true, then you can set fields in the request that control how the returned data is grouped, making "pages' that can be managed from within your application.

You can set:

  • pageSize – the number of results returned for each page
  • firstPage – whether the current result is the first page
  • lastPage – whether the current result is the last page
  • totalPages – the total number of pages returned
  • pageNumber – the current page number. This starts at 0.

The second sample shows the response from the Radioplayer Partner API (WRAPI) containing these values.

For more explicit information on the pagination fields, see the API Reference.

Object Models

The main object model used in the Radioplayer Partner API (WRAPI) is the stations object.

A stations object describes everything about a radio station, including its:

  • Geolocation
  • Bearer information
  • Social media
  • Supporting branding and images

as well as a host of other information.

You can view the station object model here.

Technical FAQs

  1. What is [this] field for?

    Our API documentation in this section will explain what each field is used for. We never change the name of a field across endpoints.

  2. I think I’ve found something in the data that doesn’t look right. Can I report it?

    Yes, you can email your account manager. Please provide as much detail as you are able about the issue.

  3. Why do you sometimes return no show images or a station logo instead of a show image?

    If a broadcaster has chosen not to provide a logo for a programme episode or series, we aren’t able to aggregate what we don’t have so at times we will fall back to a station logo.

  4. I see references to images. How do I get access to them and should I host them?

    Access to images is included in your trial licence. We don’t prohibit the caching of image assets in your middleware but you should ensure you have stored the most recent version. All images have a timestamp in their URL which will help identify if the asset you’ve cached is the latest version.

  5. I’m making a call but getting an error message. What does this mean?

    The list of error codes is listed earlier on this page. If you see errors in the 5xx range, you may need to wait some time before retrying.

  6. I need data in XML instead of JSON. Is this supported?

    The default response format is JSON, but basic support for XML responses is included. To receive your response as XML add an xml=true parameter to your URL, or set a request header of Accept: 'application/xml'.

  7. I made a call and I’m not receiving data in the response or the response body is empty. What’s wrong?

    If you receive an empty body (or a response containing just []) it means that although the request was valid, there was no matching metadata. This is usually due to parameter names being correct but values being invalid. Sometimes, however, this is because the request you made is taking some time to compute - perhaps you’ve asked for a large number of objects or have submitted a complex search or recommendation query. Allow a generous timeout but if you experience performance problems, consider simplifying or splitting up your requests.

  8. Is there a limit to the number of requests I can make per second or to the number of calls per day?

    Yes, rating limiting and quota management measures are in place. We set rate limits per second and quotas per month (allowing for peaks and troughs across the month).

  9. Do you support gzip?

    Yes all our responses are gzipped and we recommend your application supports it.

  10. Do you have different versions of your API? What happens if you introduce a new version whilst I’m on an older version?

    We support older versions for at least six months and typically longer. Endpoint URLs show the current version. We try to maintain backwards compatibility too, but if a breaking change is likely you will receive at least six months notice.

  11. Is there an API health or status page?

    We monitor our APIs 24/7. In the event of an outage or planned maintenance, a message will be posted on the homepage of this site.

  12. Which countries do you support?

    We currently make metadata available for United Kingdom, Ireland, Canada, Norway, Denmark, Belgium, Germany, Austria, Switzerland, Spain and Italy. Refer to ISO 3166 for the corresponding country codes.

Contact Us

Still have questions or comments? Please contact us.