Search for and retrieve on-demand content
/ondemand
Returns information about on-demand content, based on:
- text search,
- station,
- country, or
- category.
It is possible to search solely by country, but if using a text-based search or a category search, the country
parameter must also be included in the query string.
Endpoint
Base URL: https://api.radioplayer.org/v2/ondemand
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 Parameters
Look up on demand by country
v2/ondemand/?country=372
Search on demand by category
/v2/ondemand?country=826&category=urn:radioplayer:metadata:cs:Category:2012:5
Search on demand by country
/v2/ondemand?country=826&search=mckinney
QUERY PARAMETER | VALUE |
---|---|
country |
Required in all cases. Takes an ISO 3166 numeric country code. When applied only returns results from the specified country. |
category |
Optional. Search for on-demand items by category. The category identifiers can be found by querying the categories endpoint and using the returned href values (URI-encoded) as the parameter value.Requires the country parameter as part of the query string. |
search |
Optional. Returns on-demand content that contains a specified text string. Requires the country parameter as part of the query string.Example: |
rpuids |
Optional. A comma separated list of station unique IDs |
Response
When successful, the HTTP status code in the response header is 200 OK.
content-type: application/json; charset=utf-8
x-ratelimit-limit: 300000
x-ratelimit-remaining: 285030
x-ratelimit-reset: 1585699200
An array of onDemandStreams objects meeting the search criteria are returned in JSON format (or on special request, XML supported by the RadioDNS schema).
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": [
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmy3/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-25T15:30:00Z",
"availableStop": "2020-04-24T15:30:00Z"
}
],
"alphanumericKey": "a",
"series": {
"id": "afternoonconcert"
},
"description": "Tom McKinney presents a week of concerts featuring the BBC National Orchestra of Wales, including a series of works by the celebrated composer Grace Williams.",
"name": "Afternoon Concert : 25/03/2020",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000gmy4",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p061ztrw.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glxl/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-26T17:00:00Z",
"availableStop": "2020-04-25T17:00:00Z"
}
],
"alphanumericKey": "a",
"series": {
"id": "afternoonconcert"
},
"description": "Opera Matinee: Gounod's Romeo and Juliet from the Royal Opera House, Covent Garden.",
"name": "Afternoon Concert : 26/03/2020",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000glxm",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmyp/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-27T09:00:00Z",
"availableStop": "2020-04-26T09:00:00Z"
}
],
"alphanumericKey": "b",
"series": {
"id": "breakfast"
},
"description": "Petroc Trelawny presents Radio 3's classical breakfast show, featuring listener requests and the Friday poem. Email [email protected]",
"name": "Breakfast : Friday - Petroc's classical commute",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000gmyq",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glxb/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-26T09:00:00Z",
"availableStop": "2020-04-25T09:00:00Z"
}
],
"alphanumericKey": "b",
"series": {
"id": "breakfast"
},
"description": "Petroc Trelawny presents Radio 3's classical breakfast show, featuring listener requests. Email [email protected]",
"name": "Breakfast : Thursday - Petroc's classical picks",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000glxc",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p01r0t7b.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmxv/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-25T09:00:00Z",
"availableStop": "2020-04-24T09:00:00Z"
}
],
"alphanumericKey": "b",
"series": {
"id": "breakfast"
},
"description": "Petroc Trelawny presents Radio 3's classical breakfast show, featuring listener requests. Email [email protected]",
"name": "Breakfast : Wednesday - Petroc's classical alarm call",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000gmxw",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p01nl6fq.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p01nl6fq.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p01nl6fq.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmy5/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-25T16:30:00Z",
"availableStop": "2020-04-24T16:30:00Z"
}
],
"alphanumericKey": "c",
"series": {
"id": "choralevensong"
},
"description": "From the Temple Church, London for the Feast of the Annunciation of Our Lord to the Blessed Virgin Mary (recorded 25th February).",
"name": "Choral Evensong : The Temple Church, London",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000gmy6",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glxg/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-26T13:00:00Z",
"availableStop": "2020-04-25T13:00:00Z"
}
],
"alphanumericKey": "c",
"series": {
"id": "composeroftheweek"
},
"description": "Beethoven had left most of his friends and family behind in Bonn. He didn't want for company in Vienna but lacked a soulmate he could confide in. Presented by Donald Macleod.",
"name": "Composer of the Week : Finding Friends",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000glxh",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p07xsj4q.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gmxz/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-25T13:00:00Z",
"availableStop": "2020-04-24T13:00:00Z"
}
],
"alphanumericKey": "c",
"series": {
"id": "composeroftheweek"
},
"description": "Beethoven was a reluctant teacher, but was moved to make a special effort for one or two especially charming and talented piano students. Presented by Donald Macleod.",
"name": "Composer of the Week : Teacher's Pets",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000gmy0",
"country": "826",
"rpuid": "826343"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p05nc8rj.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p05nc8rj.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p05nc8rj.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000gn23/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-26T22:00:00Z",
"availableStop": "2020-04-25T22:00:00Z"
}
],
"alphanumericKey": "c",
"series": {
"id": "thecountryshowwithbobharris"
},
"description": "Bob's self-isolating at home, but that's not stopped him bringing you the best country music around, with new songs from Lainey Wilson, Kenny Chesney & Rumer among others!",
"name": "The Country Show with Bob Harris : Bob's self-isolating, so it's country from the country!",
"id": "826342:sp:/crid://www.bbc.co.uk/programmes/m000gn24",
"country": "826",
"rpuid": "826342"
},
{
"multimedia": [
{
"url": "http://ichef.bbci.co.uk/images/ic/86x48/p0428n3t.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 86,
"height": 48,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/288x162/p0428n3t.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 288,
"height": 162,
"index": 0
},
{
"url": "http://ichef.bbci.co.uk/images/ic/160x90/p0428n3t.jpg",
"mimeValue": "image/jpeg",
"language": "en",
"width": 160,
"height": 90,
"index": 0
}
],
"onDemandStreams": [
{
"streamSource": {
"url": "http://open.live.bbc.co.uk/mediaselector/5/select/version/2.0/proto/http/format/json/vpid/m000glxd/mediaset/",
"mimeValue": "application/vnd.bbc-mediaselector+json"
},
"bitRate": {
"target": 128000
},
"availableStart": "2020-03-26T12:00:00Z",
"availableStop": "2020-04-25T12:00:00Z"
}
],
"alphanumericKey": "e",
"series": {
"id": "essentialclassics"
},
"description": "Refresh your morning with a great selection of classical music, presented by Ian Skelly.",
"name": "Essential Classics : Ian Skelly with Essential Brahms, Sallinen's Sunrise Serenade, Colonel Bogey",
"id": "826343:sp:/crid://www.bbc.co.uk/programmes/m000glxf",
"country": "826",
"rpuid": "826343"
}
],
"meta": {
"nesting": false,
"dataType": "ondemand",
"count": 10,
"fromCache": true,
"cacheExpiresAt": 1585337220266,
"paginated": false
}
}
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 false by default.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 . The items are returned in a nested list.For more information on nesting, see the API Documentation index. |
dataType |
Object type returned by the request. In this case it 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 expected data
field values for this endpoint are:
FIELD | VALUE |
---|---|
id |
String. Unique identifier for the request on-demand item. |
multimedia |
Object. Specifying the available image assets |
↳ url |
URL. The URL of the visual asset. |
↳ language |
String. Language of the image asset. Useful for image that may display lines of text |
↳ type |
String, constant. This is always logo_unrestricted as per the DAB-EPG spec |
↳ width |
Integer. The number of pixels representing the width of the image. |
↳ height |
Integer. The number of pixels representing the height of the image. |
↳ index |
Integer. Where multiple images of the same size are offered, the index indicates the order to try each resource with 0 being the most preferred asset. |
onDemandStreams |
Object. Describes the available audio streams for the on-demand content |
streamSource |
Object. One or multiple objects which describe the available streams |
↳ url |
String. The URL for the available audio stream |
↳ mimeValue |
String. MIME type of the audio stream |
bitrate ↳ target |
Integer. The quoted bitrate of the stream in bits per second |
↳ availableStart |
RFC Timestamp. The date and time (in GMT) of when the audio stream can be made available to the public. |
↳ availableStop |
RFC Timestamp. The date and time (in GMT) of when the audio stream must be withdrawn from public access |
series |
Object. Where an on-demand episode is part of a series, this object provides additional information. |
↳ id |
String. An identifier of the parent series to which this episode relates |
description |
String. A short textual description of the programme |
name |
String. The name of the episode. |
alphanumericKey |
String. Where an item of content is listed in an alphabetical list, this key indicates the letter of the alphabet under which the content should appear. |
rpuid |
Integer. A unique identifier relating to the radio station that published the OD content |
country |
Integer. ISO numeric country code of the station that published the OD content. |