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.

API Reference