API Reference

Retrieve recent on-demand content as part of a series

/stations/{rpuid}/ondemand/{seriesId}

Returns a paginated subset of on demand items for a given series. Results are returned in chronological order, the most recent first. A specific station which is identified by its rpuid must be stated too.

This is organised into a paginated array.

Endpoint

Base URL: https://api.radioplayer.org/v2/stations/{rpuids}/ondemand/{seriesId}

Request Parameters

Header Fields

To find out how to correctly construct authentication headers for the Radioplayer Partner API (WRAPI) please see the Authentication guide.

Path Parameters

Lookup series by id

/v2/stations/826340/ondemand/newsbeat
PATH PARAMETER VALUE
{rpuid} Specifies a single station object by its rpuid.
{seriesId} Identifies a series as hosted by a specific station.

In the case of this endpoint only one seriesId can be returned at time.

Query Parameters

QUERY PARAMETER VALUE
page Optional. If the results are paginated, this specifies which page is returned
size Optional. This specifies the maximum number of results to return in the response. If not set, all results will be returned in paginated form.

Response

When successful, the HTTP status code in the response header is 200 OK.

A subset of onDemandStreams objects, with a specific seriesId attached, and listed in chronological order with the most recent first, 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.

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": [
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gmj9",
        "locations": [
            {
            "scheduledStart": "2020-03-27T12:45:00Z",
            "scheduledStop": "2020-03-27T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-27T12:45:00Z",
            "scheduledStop": "2020-03-27T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-27T12:45:00Z",
            "scheduledStop": "2020-03-27T13:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmj8/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-27T13:00:00Z",
            "availableStop": "2020-04-26T13:00:00Z"
            }
        ],
        "description": "Thousands of people across the UK stop and clap to show their appreciation for health and care workers, but what else can we do to help?",
        "name": "Newsbeat : Clap for Carers gets emotional",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p087w36s.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gn19",
        "locations": [
            {
            "scheduledStart": "2020-03-26T17:45:00Z",
            "scheduledStop": "2020-03-26T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-26T17:45:00Z",
            "scheduledStop": "2020-03-26T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-26T17:45:00Z",
            "scheduledStop": "2020-03-26T18:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gn18/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-26T18:00:00Z",
            "availableStop": "2020-04-25T18:00:00Z"
            }
        ],
        "description": "If you're still thinking about meeting up with mates... have a listen to Olivia's story. Also, the government reveals financial support for the UK's self-employed.",
        "name": "Newsbeat : Keep Your Distance",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p06s6rc4.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gn13",
        "locations": [
            {
            "scheduledStart": "2020-03-26T12:45:00Z",
            "scheduledStop": "2020-03-26T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-26T12:45:00Z",
            "scheduledStop": "2020-03-26T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-26T12:45:00Z",
            "scheduledStop": "2020-03-26T13:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gn12/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-26T13:00:00Z",
            "availableStop": "2020-04-25T13:00:00Z"
            }
        ],
        "description": "We have the latest on coronavirus as self-employed workers are set to get financial help from the government. Also, we answer more of your questions about the outbreak.",
        "name": "Newsbeat : Help for Self-employed",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p06s6rc4.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gm0z",
        "locations": [
            {
            "scheduledStart": "2020-03-25T17:45:00Z",
            "scheduledStop": "2020-03-25T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-25T17:45:00Z",
            "scheduledStop": "2020-03-25T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-25T17:45:00Z",
            "scheduledStop": "2020-03-25T18:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gm0x/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-25T18:00:00Z",
            "availableStop": "2020-04-24T18:00:00Z"
            }
        ],
        "description": "Around 250,000 have signed up to volunteer with the NHS to help tackle the coronavirus.",
        "name": "Newsbeat : Thousands volunteer to help the NHS",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p087myyr.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gm0l",
        "locations": [
            {
            "scheduledStart": "2020-03-25T12:45:00Z",
            "scheduledStop": "2020-03-25T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-25T12:45:00Z",
            "scheduledStop": "2020-03-25T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-25T12:45:00Z",
            "scheduledStop": "2020-03-25T13:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gm0j/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-25T13:00:00Z",
            "availableStop": "2020-04-24T13:00:00Z"
            }
        ],
        "description": "Thousands of people have responded to a call for volunteers to help the NHS. We've also got advice for pet owners on how to deal with being stuck inside.",
        "name": "Newsbeat : The NHS needs volunteers",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p06s6rpp.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000glkr",
        "locations": [
            {
            "scheduledStart": "2020-03-24T17:45:00Z",
            "scheduledStop": "2020-03-24T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-24T17:45:00Z",
            "scheduledStop": "2020-03-24T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-24T17:45:00Z",
            "scheduledStop": "2020-03-24T18:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glkp/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-24T18:00:00Z",
            "availableStop": "2020-04-23T18:00:00Z"
            }
        ],
        "description": "We answer your questions about the UK's shutdown designed to slow the spread of coronavirus. Plus, advice on how to protect your mental health in these weird times.",
        "name": "Newsbeat : Life Under Lockdown",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p087jlsl.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000glkc",
        "locations": [
            {
            "scheduledStart": "2020-03-24T12:40:00Z",
            "scheduledStop": "2020-03-24T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-24T12:40:00Z",
            "scheduledStop": "2020-03-24T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-24T12:40:00Z",
            "scheduledStop": "2020-03-24T13:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glk9/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-24T13:00:00Z",
            "availableStop": "2020-04-23T13:00:00Z"
            }
        ],
        "description": "We look at the new restrictions on your life, designed to help slow the spread of coronavirus. We'll try to answer as many of your questions about it as we can.",
        "name": "Newsbeat : The UK In Shutdown",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p087hljd.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000glhv",
        "locations": [
            {
            "scheduledStart": "2020-03-23T17:45:00Z",
            "scheduledStop": "2020-03-23T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-23T17:45:00Z",
            "scheduledStop": "2020-03-23T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-23T17:45:00Z",
            "scheduledStop": "2020-03-23T18:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glht/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-23T18:00:00Z",
            "availableStop": "2020-04-22T18:00:00Z"
            }
        ],
        "description": "NHS workers tell us why you must stay at home to prevent coronavirus spreading as some doctors call for tougher measures.",
        "name": "Newsbeat : More Movement Restrictions?",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p06s6rc4.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000glhn",
        "locations": [
            {
            "scheduledStart": "2020-03-23T12:45:00Z",
            "scheduledStop": "2020-03-23T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-23T12:45:00Z",
            "scheduledStop": "2020-03-23T13:00:00Z"
            },
            {
            "scheduledStart": "2020-03-23T12:45:00Z",
            "scheduledStop": "2020-03-23T13:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glhm/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-23T13:00:00Z",
            "availableStop": "2020-04-22T13:00:00Z"
            }
        ],
        "description": "NHS workers tell us why you must stay at home to prevent coronavirus spreading. Plus, McDonald's and Nando's close all their restaurants.",
        "name": "Newsbeat : Stopping The Spread",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p087dkmk.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        },
        {
        "id": "826340:sp:/crid://www.bbc.co.uk/programmes/m000gcgb",
        "locations": [
            {
            "scheduledStart": "2020-03-20T17:45:00Z",
            "scheduledStop": "2020-03-20T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-20T17:45:00Z",
            "scheduledStop": "2020-03-20T18:00:00Z"
            },
            {
            "scheduledStart": "2020-03-20T17:45:00Z",
            "scheduledStop": "2020-03-20T18:00:00Z"
            }
        ],
        "onDemandStreams": [
            {
            "streamSource": {
                "url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gcg9/mediaset/",
                "mimeValue": "application/vnd.bbc-mediaselector+json"
            },
            "bitRate": {
                "target": 128000
            },
            "availableStart": "2020-03-20T18:00:00Z",
            "availableStop": "2020-04-19T18:00:00Z"
            }
        ],
        "description": "Students react to how GCSE and A-Levels will be graded now exams have been cancelled, plus the latest measures from the Government to help protect jobs in the UK.",
        "name": "Newsbeat : Exams, school closures and help to protect jobs",
        "multimedia": [
            {
            "url": "http://ichef.bbci.co.uk/images/ic/288x162/p08750tr.jpg",
            "mimeValue": "image/jpeg",
            "language": "en",
            "width": 288,
            "height": 162,
            "index": 0
            }
        ],
        "country": "826",
        "rpuid": "826340",
        "series": {
            "id": "newsbeat"
        }
        }
    ],
    "meta": {
        "nesting": false,
        "dataType": "ondemand",
        "count": 10,
        "fromCache": false,
        "cacheExpiresAt": 1585328411474,
        "paginated": true,
        "pageSize": 10,
        "lastPage": false,
        "firstPage": true,
        "totalPages": 5,
        "pageNumber": 0
        }
    }

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.

In this endpoint, paginated is set to true.

For more information on pagination, see the API Documentation index.
nesting Optional, Boolean. Indicates whether full data objects are nested within other objects.

In this endpoint, nesting is set to false.

For more information on nesting, see the API Documentation index.
dataType Object type returned by the request. In this case the object is ondemand.
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

For more information on caching, please see the API Documentation index.
cacheExpiresAt Optional. UNIX timestamp indicating when the cache will expire.

For more information on caching, please see the API Documentation index.

The possible data field values for this endpoint are:

FIELD VALUE
id String. This is an identifier which refers to the episode of the show
locations
↳ scheduledStart
Optional, date. Where a series has been broadcast, there will be one or many pairs of scheduledStart and scheduledStop entries relating to the start and end times when the programme was originally broadcast. RFC3339 formatted date.
locations
↳ scheduledEnd
Optional, date. RFC 3339 formatted date, rules as above, marking end date/time of original broadcast.
onDemandStreams Optional, Array. An array of audio streams representing the programme. There may be multiple streams for a single broadcast and where provided, their child elements are outlined below.
onDemandStreams
↳ streamSource
↳ url
Optional, URL. Where a programme has an audio stream available, this URL determines its location. If no URL is stated, it should be assumed the broadcast is not available for replay.
onDemandStreams
↳ streamSource
↳ mimevalue
Optional, String. A string representing the MIME type of the associated stream URL.
onDemandStreams
↳ bitrate
↳ target
Integer. An integer describing the audio bitrate in bits per second (bps). In the event of a variable or average bitrate stream, this figure is the target bitrate but is subject to the expected variations
onDemandStreams
↳ available
↳ End
Date. An RFC 3339 formatted date value describing the date beyond which it is permissible to make the stream available for playback by the public. The stream must not be made available before this date.
onDemandStreams
s↳ cheduledStart
Date. An RFC 3339 formatted date describing the final date, beyond which you must cease distribution of the audio stream. The public must not be able to access the stream after this point.
description Optional, String. A short (128 char max) description of the episode of the programme.
name String. A string describing the title of the episode.
multimedia Array. Where provided, this is an array of visual assets such as episode or series images depicting the programme. There may be none, one or many images available.
multimedia
↳ url
URL. The URL of the visual asset.
multimedia
↳ mimeValue
String. A string describing the MIME type of the visual asset such as image/jpeg
multimedia
↳ width
Integer. The width of the visual asset in pixels.
multimedia
↳ height
Integer. The height of the visual asset in pixels.
locations
↳ index
Integer. Where multiple images are provided, this value indicates the image to attempt to use first, where the lower the value, the higher the priority.