API Reference

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/stations/?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.