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
Parameter
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/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