BBC Audio on Demand XML Feed (aka. BBC AOD Feed)


Last update: 2011-04-12 - added comment about RDF retrieval.

Intro

We recognised that various activites around our web presence - RadioPlayer - had built up over the years, and we were quietly working to replace this unsupported activity with something more supported and more sensible. (Screenscaping - euch!)

 

On the drawing board was an XML feed that could be requested to get the data that would help others build applications or websites around our data. The most notable of this - device manufacturers who wish to put our available Audio on Demand (so called 'Listen Again') in their device's navigation.

 

With the recent internal activities to get TV and Radio more integrated together on the web in one place (iPlayer) there was a clear set of requirements which fell out of those decisions. This data feed is one of them, and this document describes how this can be used.

 

This document is the product of initial documentation and feedback from an initial user group. We started this in early July 08.

 

Please also remember the usage terms of the feed which are highlighted at the start of the XML and you should contact us if you need to get permission to use anything. We'd also be interested to hear about services you've built using this.

Usage of this feed does not authorise you to use items of BBC copyright or trademarks (eg. the BBC Logo, BBC Radio brands). Please email aodfeed@bbc.co.uk for full details - graphical assets and correct naming techniques can be provided once you agree to our brand usage and linking terms.

Please also be aware that the defintion/schema of this XML may change. We will attempt to inform you if you contact us at that same email address and tell us what you are using it for (with a link if appropriate). We may implement an API-Key or similar for continued access to this data source - to allow us to monitor and provide appropriate service levels to support those using it fairly.

 

As ever, we're looking for feedback. We've even put in a list of areas which we know are issues.

 

Thanks.

 

Alan Ogilvie alan.ogilvie@bbc.co.uk

 

(You can also email aodfeed@bbc.co.uk directly which will be forwarded to all those involved in this)

 


 

Location of feeds

http://www.bbc.co.uk/radio/aod/availability/...

 

The individual xml files available here are:

 

radio1.xml - BBC Radio 1

1xtra.xml - BBC 1Xtra

radio2.xml - BBC Radio 2

6music.xml - BBC 6Music

radio3.xml - BBC Radio 3

radio4.xml - BBC Radio 4 (includes both FM and LW services)

radio4extra.xml - BBC Radio 4 Extra (new as of 2011-04-02 0659BST)

bbc7.xml - BBC Radio 7 (deprecated from 2011-04-02 0700BST - will end updating a week after this date)

fivelive.xml - BBC Radio 5live

sportsextra.xml - BBC Radio 5live Sports Extra

asiannetwork.xml - BBC AsianNetwork

 

alba.xml - BBC Radio nan Gaidheal

radioscotland.xml - BBC Radio Scotland

radioulster.xml - BBC Radio Ulster

radiofoyle.xml - BBC Radio Foyle

radiowales.xml - BBC Radio Wales

radiocymru.xml - BBC Radio Cymru

Local Radio services:

bbc_london.xml

bbc_radio_berkshire.xml

bbc_radio_bristol.xml

bbc_radio_cambridge.xml

bbc_radio_cornwall.xml

bbc_radio_coventry_warwickshire.xml

bbc_radio_cumbria.xml

bbc_radio_derby.xml

bbc_radio_devon.xml

bbc_radio_essex.xml

bbc_radio_gloucestershire.xml

bbc_radio_guernsey.xml

bbc_radio_hereford_worcester.xml

bbc_radio_humberside.xml

bbc_radio_jersey.xml

bbc_radio_kent.xml

bbc_radio_lancashire.xml

bbc_radio_leeds.xml

bbc_radio_leicester.xml

bbc_radio_lincolnshire.xml

bbc_radio_manchester.xml

bbc_radio_merseyside.xml

bbc_radio_newcastle.xml

bbc_radio_norfolk.xml

bbc_radio_northampton.xml

bbc_radio_nottingham.xml

bbc_radio_oxford.xml

bbc_radio_sheffield.xml

bbc_radio_shropshire.xml

bbc_radio_solent.xml

bbc_radio_somerset_sound.xml

bbc_radio_stoke.xml

bbc_radio_suffolk.xml

bbc_radio_swindon.xml

bbc_radio_wiltshire.xml

bbc_radio_york.xml

bbc_southern_counties_radio.xml

bbc_tees.xml

bbc_three_counties_radio.xml

bbc_wm.xml (BBC Birmingham)

World Service:

worldservice.xml - currently not working satisfactorily be wary of the output.

Frequency of update

Every 3 hours, it contains everything that is available now (as per update). It also contains everything that will become available in the next 48 hours.

Features

Let's take a look at some of the features of the xml, using the xml Radio 4 file as an example:

 

<schedule start_date="2008-07-16T18:00:16Z" end_date="2008-07-18T18:00:16Z" network="radio4" updated="2008-07-16T18:02:14Z">

 <title>BBC Audio On Demand Availability Schedule</title>

 <usage>Usage of this feed does not authorise you to use items of BBC copyright or trademarks (eg. the BBC Logo, BBC Radio brands).Please email aodfeed@bbc.co.uk for full details - graphical assets and correct naming techniques can be provided once you agree to our brand usage and linking terms.</usage>

 <contact>aodfeed@bbc.co.uk</contact>

 <copyright>British Broadcasting Corporation [c] 2008</copyright>

 <entry>

  <key>8f711cc8b136e4fc27d3bde062a59b0e3e04f315</key>

  <pid>b007gz6c</pid>

  <service>bbc_radio_fourfm</service>

  <title>Fabulous, Series 1, Episode 1</title>

  <synopsis>Sitcom about a woman who wants to be Fabulous but can't cope.</synopsis>

  <availability start="2008-07-16T22:32:00Z" end="2008-07-23T22:32:00Z"/>

  <broadcast pid="b007gz5k" imi="imi:bbc.co.uk/AMI_89175334fe2f7e9e2f86ceb4cb59f953" start="2007-05-16T22:00:00Z" end="2007-05-16T22:15:00Z" duration="900"/>

  <parents>

   <parent pid="b007j2mh" type="Series">Series 1</parent>

   <parent pid="b007nqhm" type="Brand">Fabulous</parent>

  </parents>

  <links>

   <link type="mediaselector">http://www.bbc.co.uk/mediaselector/4/mtis/stream/b007gz5k</link>

  </links>

 </entry>

...

..

.

</schedule>

 

There are multiple 'entry' nodes which you can gather the availability of media from - here's some notes about various interesting nodes and attributes - everything else should be obvious (but then please don't hesitate to ask if they aren't):

/schedule/entry/key

This string represents a hash of a few things within this entry that give you a unique identifier allowing you to identify entries you've seen before in a previous request of the xml. If you are putting your data in a database - this is your route to keeping things unique and up-to-date. We don't plan on using this key value anywhere else, we just thought putting it here would make it easier for you so you didn't have to calculate this yourself.

/schedule/entry/pid

Now, this is really good. The value stored in the node is an identifier that can be used in a number of URI recipes if you need more information. Here's a few useful recipes (replace ':pid' with the value in the node):

/schedule/entry/service

Upon first encounter, it seems that the service node is unnecessary as we already split the xml files themselves up based on the network. However - in the example of Radio 4 - we actually have two possible sub-services within the Radio 4 brand - FM and LW. The same split happens on the 5live xml - between 5live and 5live Sports Extra.

You can happily ignore this node if you don't want, or need, to distinguish this nuance.

/schedule/entry/availability

This node contains two attributes that give you details of when the media is available, or will become available. The timestamps here are defined in Zulu Time (UTC).

/schedule/entry/broadcast

The broadcast child contains the start and end time of the original broadcast of the content. Timestamps defined in Zulu Time.

By the way - the pid attribute here is actually the vpid - I only mention this so you do not confuse with the /schedule/entry/pid - the vpid is the version pid, at this time it is unlikely to change as we do not currently support multiple versions of the same content.

Duration is specified in seconds. This may differ from the actual duration of the media file - but should be used for display purposes.

/schedule/entry/parents

This gives a list of parent objects' PIDs (unique identifiers). These come in a few different types - but you could be interested in 'brand' or 'series'.

Consider 'The Archers' on Radio 4 - the episode from 10/07/2008 has a /schedule/entry/pid of 'b00cdf8q' - the parent brand pid is listed as 'b006qpgr'. For which you could use some of the same recipes above - in this case if you look at:

http://bbc.co.uk/programmes/b006qpgr

you get a full list of all the episodes of the archers. So if you use a clever xpath query against this XML data to isolate all 'entry' nodes which have parents/parent/@type = 'Brand' and parents/parent/@pid = 'b006qpgr' then you should get a full list of available 'The Archers' episodes.

http://bbc.co.uk/programmes/b006qpgr/microsite gives you a link to the Archers website.

Nice?

The parents also have a text description, just in case you want to do similar with 'Series' types.

/schedule/entry/links

Here's the bit that gives you the stream urls. We decided to go for some future proofing here, so it might seem a little odd that links only contains one child node called 'link' but this might be need later when some other changes happen. (obviously I'll keep you updated when this happens).

Right now - this is simply a link to our 'media selector' tool which serves up the following lump of xml. We went with putting this as a link which you'll need to scrape yourselves because of the newly dynamic RAM files (yes - this is *really* important - we no longer have filenames that stay the same).

Here's an example (retrieved from

http://www.bbc.co.uk/mediaselector/4/mtis/stream/b00chbpx )

 

<?xml version="1.0" encoding="UTF-8"?>

<mediaSelection xmlns="http://bbc.co.uk/2008/mp/mediaselection">

 <media kind="audio" type="audio/mpeg" encoding="mp3">

  <connection priority="10" kind="akamai" server="cp48186.edgefcs.net" identifier="mp3:secure/radio4/AMI_0f2c8dff86e9a17f6862c0543423c869_b00chbpx_0000_sun" authString="daEbGbHaRd4b4b5aFcjcHdFd9aVd_aMc_aQ-biFMaB-cCp-DooDDqCoLCuEoyL"/>

 </media>

 <media kind="audio" type="audio/real" encoding="real">

  <connection priority="10" kind="sis" server="http://www.bbc.co.uk" identifier="/radio/aod/playlists/xp/bh/c0/0b/2300_bbc_radio_fourfm" href="http://www.bbc.co.uk/radio/aod/playlists/xp/bh/c0/0b/2300_bbc_radio_fourfm.ram"/>

 </media>

</mediaSelection>

 

Note that media selector maintains the availability window for us now, and you might find that when you click the link above that it says the media isn't available. You'll be interested in /mediaSelection/media/@encoding = real for the moment. Ignore the MP3 one because that's the 'secure' stream used in iPlayer. (I understand we aren't giving you any insider knowledge here because it's published within the HTML on the iPlayer pages). So extracting the URL of the metafile for the stream from /mediaSelection/media/connection/@href will give you what you need to aggregate.

Gotchas, Known Bugs and Wish-lists

1. No XML declaration present at the start of the xml files. No definition of the language support. At this time, you can assume it's XML 1.0, and the language is UTF-8. We are currently trying to confirm the actual storage method and we failed to get it in for launch. This will probably be fixed when World Service joins us on this, but I'm giving no commitment at the current time as to when, or if, that will happen.

 

2. Why isn't it an ATOM feed / or some other standardised feed? This has been frequently asked - we considered ATOM, but haven't been given any good reason why we should use it. ATOM or RSS sort of imply the xml has changes appended and old stuff removed from it, but currently the xml we are producing doesn't act like this - this was one of the arguments for not putting it in either of those formats. If you feel strongly that it should be in these or other formats, then we're waiting to hear your argument(s).

 

3. What is the .../broadcast/@imi attribute? Curious folk have asked this question - it's for internal BBC uses. It's an identifier to an internal system, we decided to expose it because we believe that internal BBC folk might/will need it at some point.

 

4. "You mention aodfeed@bbc.co.uk but that email address just bounces, why?" - sorry it's in the middle of being set up, it takes a while for that type of thing to happen. In the meantime feel free to email me at firstname.lastname@bbc.co.uk with any questions.

 

5. Your comments here! - send me your experiences of using the feed, or any features you'd like to see added.

 

6. Migration from old system (RadioPlayer and the CPS systems behind that) to the new system (iPlayer and the new CPS systems behind that) - I handled this in an email sent to the first group who saw this new feed: Jan 2010: Local Radio has joined in and I have updated the list of available XML files to reflect this. World Service (worldservice.xml) does exist but we are currently having issues.

 

-----Original Message-----

From: Alan Ogilvie

Sent: 17 July 2008 15:57

To: Alan Ogilvie

Subject: [NDA-ANNOUNCE] Launched - the new AOD feed! (minor caveat)

 

It looks like there is a minor caveat to this at the moment.

 

As some networks migrate across to the new iPlayer infrastructures the XML feeds we have may not give us the availability of *everything*.

 

My initial attempt at writing this email came up with a valid flowchart of how to interpret between the XML feeds and the existing RadioPlayer website.

 

I scrapped it - it was too confusing because of the complexities involved, and to ask you to do this would be insane.

 

So - I want to recommend that we continue to trust the XML feeds, as they will eventually be correct. (When I say 'eventually' I mean in a matter of days.)

 

Radio 4, for example, is still being migrated - and so you'll find it still listed on RadioPlayer <http://www.bbc.co.uk/radio/aod/> - in this example some of the XML returns information that the show isn't available.

I say - hang in there, it'll sort itself because of the ongoing production of new media files and the update of the XML feeds.

I also want to take the opportunity to apologise if you feel I've not been giving you enough information upfront about things. It is often difficult to get priorities for projects within the structure of a very large organisation - iPlayer and RadioPlayer are two very large 'products' and as with any engineering/re-engineering project priorities are changed based on audience, value.

Local Radio and WorldService are something we'll be working with those teams. International audience are still issues - but I mentioned that in the Codecs email I sent previously.

Alan