Radio Pop

Developer API

Radio Pop provides a comprehensive API allowing anyone to develop widgets and gizmos to display the data. We are only providing user-related information at the moment but we are looking at adding aggregated statistics as well. Let us know if there's anything in particular you might want.

The API is REST style and all API methods are accessed using HTTP GET with appropriate parameters. All calls will return XML wrapped in an <rsp> node. Incorrect parameters are just ignored.

Users
Listens
Pops
Input
APML

User information

Get information about a user - when they joined and what they last listened to.

/users/<username>.xml

Parameters

username

required

The username for the user

Example

http://www.radiopop.co.uk/users/tristanf.xml

Sample response

<rsp stat="ok">
  <user>
    <member_since>2008-07-28T17:02:53+01:00</member_since>
    <username>tristanf</username>
    <profile>
      http://www.radiopop.co.uk/users/tristanf
    </profile>
    <now_listening>
      <network id="radio4">BBC Radio 4</network>
      <programme id="b00d6zqd">Episode 1</programme>
      <series id="b00d7jcc">I Was a Child Prodigy</series>
    </now_listening>
    <last_listened>
      <network id="fivelive">BBC Radio 5 live</network>
      <programme id="b00cqh74">29/07/2008</programme>
      <brand id="b0070lvr">Drive</brand>
    </last_listened>
  </user>
</rsp>

User friends

Get a list of a user's friends.

/users/<username>/friends.xml

Parameters

username

required

The username for the user whose friend are requested

Example

http://www.radiopop.co.uk/users/tristanf/friends.xml

Sample response

<rsp stat="ok">
  <user>
    <username>fridayforward</username>
  </user>
  <friends>
    <friend>
      <username>tom</username>
      <profile>http://www.radiopop.co.uk/users/tom</profile>
    </friend>
    <friend>
      <username>tristanf</username>
      <profile>http://www.radiopop.co.uk/users/tristanf</profile>      
    </friend>
  </friends>
</rsp>

User listens

Get information about listen events for a user. A listen event is a contiguous stretch of listening to a particular programme on a particular radio network. Stopping listening, a new programme starting or changing network creates a new listen event. By default this method returns the first page of all the user's listen events.

/users/<username>/listens.xml

Parameters

username	required	The username for the user
starttime	optional	Only return events after this time. Should be an ISO8601 date.
endtime	optional	Only return events before this time. Should be an ISO8601 date.
network_id	optional	Only return events on this radio network. Can be filtered by multiple networks by using multiple comma-separated network_ids. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
brand_id	optional	Only return events for this brand. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).
per_page	optional	Specifies the number of events to be viewed per page. Default is 25.
page	optional	Specifies which page the result set should start on. Default is 1.
sort	optional	Specifies the sort order. Default is newest first or for oldest first use: chronological

Example

/users/tristanf/listens.xml
/users/tristanf/listens.xml?starttime=2008-05-20T12:00:00
/users/tristanf/listens.xml?network_id=radio3
/users/tristanf/listens.xml?network_id=radio3,radio4
/users/tristanf/listens.xml?page=3
/users/tristanf/listens.xml?network_id=fivelive,radio3&starttime=2008-05-20

Sample response

<rsp stat="ok">
  <listenevents per_page="25" events="1" page="1" pages="1">
    <listenevent index="1">
      <user>tristanf</user>
      <starttime>2008-07-29T15:22:18+01:00</starttime>
      <endtime>2008-07-29T15:22:21+01:00</endtime>
      <total_time>3</total_time>
      <client_id/>
      <listen_type>live</listen_type>
      <network id="radio3">BBC Radio 3</network>
      <brand id="b0071l67">Classical Collection</brand>
      <programme id="b00cy2sc">11/08/2008</programme>
    </listenevent>
  </listenevents>
</rsp>

Friends' listens

Get information about listens from a user's friends.

/users/<username>/friends/listens.xml

Parameters

username	required	The username for the user
starttime	optional	Only return events after this time. Should be an ISO8601 date.
endtime	optional	Only return events before this time. Should be an ISO8601 date.
network_id	optional	Only return events on this radio network. Can be filtered by multiple networks by using multiple comma-separated network_ids. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
brand_id	required	Only return events for this brand. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).
per_page	optional	Specifies the number of events to be viewed per page. Default is 25.
page	optional	Specifies which page the result set should start on. Default is 1.
sort	optional	Specifies the sort order. Default is newest first or for oldest first use: chronological

Example

/users/tristanf/friends/listens.xml
/users/tristanf/friends/listens.xml?network_id=fivelive,radio3&starttime=2008-05-20

Sample response

<rsp stat="ok">
  <listenevents per_page="25" events="2" page="1" pages="1">
    <listenevent index="1">
      <user>tom</user>
      <starttime>2008-08-11T16:00:42+01:00</starttime>
      <endtime>2008-08-11T17:14:42+01:00</endtime>
      <total_time>1</total_time>
      <client_id/>
      <listen_type>live</listen_type>
      <network id="fivelive">BBC Radio 5 Live</network>
      <brand id=""/>
      <programme id="b00cxmdh">11/08/2008</programme>
      <series id="b00cxr50">Olympic Drive</series>
    </listenevent>
    <listenevent index="2">
      <user>fridayforward</user>
      <starttime>2008-07-29T15:49:54+01:00</starttime>
      <endtime>2008-07-29T15:50:54+01:00</endtime>
      <total_time>2</total_time>
      <client_id/>
      <listen_type>live</listen_type>
      <network id="radio1">BBC Radio 1</network>
      <brand id="b006ww2c">Vernon Kay</brand>
      <programme id="b00cpt2t">29/07/2008</programme>
    </listenevent>
  </listenevents>
</rsp>

User pops

Get information about pops for a user. A pop is a single moment in time during a programme that a user has explicitly "popped".

/users/<username>/pops.xml

Parameters

username	required	The username for the user
starttime	optional	Only return pops after this time. Should be an ISO8601 date.
endtime	optional	Only return pops before this time. Should be an ISO8601 date.
network_id	optional	Only return pops on this radio network. Can be filtered by multiple networks by using multiple comma-separated network_ids. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
brand_id	optional	Only return pops for this brand. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).
per_page	optional	Specifies the number of pops to be viewed per page. Default is 25.
page	optional	Specifies which page the result set should start on. Default is 1.
sort	optional	Specifies the sort order. Default is newest first or for oldest first use: chronological

Example

/users/tristanf/pops.xml
/users/tristanf/pops.xml?network_id=radio3,radio4

Sample response

<rsp stat="ok">
  <popevents per_page="25" events="1" page="1" pages="1">
    <popevent index="1">
      <user>tristanf</user>
      <timestamp>2008-07-29T15:22:18+01:00</timestamp>
      <listen_type>live</listen_type>
      <client_id/>
      <network id="1xtra">1 Xtra</network>
      <brand id="b007gw82">Max</brand>
      <programme id="b00cqdq3">29/07/2008</programme>
    </popevent>
  </popevents>
</rsp>

Friends' pops

Get information about pops for a user's friends.

/users/<username>/friends/pops.xml

Parameters

username	required	The username for the user whose friends is requested
starttime	optional	Only return pops after this time. Should be an ISO8601 date.
endtime	optional	Only return pops before this time. Should be an ISO8601 date.
network_id	optional	Only return pops on this radio network. Can be filtered by multiple networks by using multiple comma-separated network_ids. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
brand_id	optional	Only return pops for this brand. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).
per_page	optional	Specifies the number of pops to be viewed per page. Default is 25.
page	optional	Specifies which page the result set should start on. Default is 1.
sort	optional	Specifies the sort order. Default is newest first or for oldest first use: chronological

Example

/users/tristanf/friends/pops.xml
/users/tristanf/friends/pops.xml?starttime=2008-05-20T12:00:00

Sample response

<rsp stat="ok">
  <popevents per_page="25" events="2" page="1" pages="1">
    <popevent index="1">
      <user>fridayforward</user>
      <timestamp>2008-07-29T15:22:18+01:00</timestamp>
      <listen_type>live</listen_type>
      <client_id/>
      <network id="1xtra">1 Xtra</network>
      <brand id="b007gw82">Max</brand>
      <programme id="b00cqdq3">29/07/2008</programme>
    </popevent>
    <popevent index="2">
      <user>fridayforward</user>
      <timestamp>2008-07-29T15:21:47+01:00</timestamp>
      <listen_type>live</listen_type>
      <client_id/>
      <network id="1xtra">1 Xtra</network>
      <brand id="b007gw82">Max</brand>
      <programme id="b00cqdq3">29/07/2008</programme>
    </popevent>
  </popevents>
</rsp>

APML

Get an APML attention profile for a user.

/users/<username>/apml

Parameters

None

Example

/users/tristanf/apml

Sample response

<apml version="0.6">
  <Head>
    <Title>APML file for tristanf from Radio Pop</Title>
    <Generator>BBC Radio Pop</Generator>
    <UserEmail/>
    <DateCreated>Wed May 21 15:56:16 +0100 2008</DateCreated>
  </Head>
  <Body defaultprofile="Radio Programmes">
    <Profile name="Radio Programmes">
      <ExplicitData>
        <Concepts>
          <Concept type="text/html" from="www.radiopop.co.uk" name="Woman's Hour" value="1.0" 
key="http://www.bbc.co.uk/programmes/b007qlvb" updated="Wed May 21 15:56:16 +0100 2008"/>
        </Concepts>
      </ExplicitData>
      <ImplicitData>
      </ImplicitData>
    </Profile>
    <Profile name="Radio Networks">
      <ExplicitData>
        <Concepts>
          <Concept type="text/html" from="www.radiopop.co.uk" name="BBC Radio 4" value="1.0" 
key="http://www.bbc.co.uk/radio4" updated="Wed May 21 15:56:16 +0100 2008"/>
        </Concepts>
      </ExplicitData>
      <ImplicitData>
      </ImplicitData>
    </Profile>
  </Body>
</apml>

OAuth

Radio Pop supports OAuth authentication for input applications. This is the method used by the Radio Pop desktop widget.

If you would like to develop an application which utilises the input API (listening and popping), please contact us for a consumer key and secret.

Listens

Radio Pop tracks users' listening through polling every minute. Client applications should poll the 'pulses' resources with the appropriate parameters once every minute.

POST /pulses

Parameters

oauth credentials	required
network_id	optional	The radio network listened to. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
programme_id	required	The programme ID for the programmebeing listened to. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).
listen_type	required	The type of listening. Should be one of: live\|ondemand

Example

oauth_consumer_key=xxxxxxx
&oauth_token=xxxxxx
&oauth_signature_method=HMAC-SHA1
&oauth_signature=xxxxxx
&oauth_timestamp=1217948506
&oauth_nonce=xxxxxx
&network_id=radio1
&listen_type=live

Pops

Record a user pop event

POST /pops

Parameters

oauth credentials	required
network_id	optional	The radio network listened to. It should be one of: radio1\|radio2\|radio3\|radio4\|fivelive\|6music\|bbc7\|1xtra\| fivelivesportsextra\|worldservice
programme_id	required	The programme ID for the programmebeing listened to. Should be a PID (the 8-character ID used in http://www.bbc.co.uk/programmes).

Example

oauth_consumer_key=xxxxxxx
&oauth_token=xxxxxx
&oauth_signature_method=HMAC-SHA1
&oauth_signature=xxxxxx
&oauth_timestamp=1217948506
&oauth_nonce=xxxxxx
&network_id=radio1
&listen_type=live

Developer API

Users

Listens

Pops

Input

APML

User information

Parameters

Example

Sample response

User friends

Parameters

Example

Sample response

User listens

Parameters

Example

Sample response

Friends' listens

Parameters

Example

Sample response

User pops

Parameters

Example

Sample response

Friends' pops

Parameters

Example

Sample response

APML

Parameters

Example

Sample response

OAuth

Listens

Parameters

Example

Pops

Parameters

Example