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

https://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>
https://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

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

Sample response

<rsp stat=”ok”>
<user>
<username>fridayforward</username>
</user>
<friends>
<friend>
<username>tom</username>
<profile>https://www.radiopop.co.uk/users/tom</profile>
</friend>
<friend>
<username>tristanf</username>
<profile>https://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