Integrating with RSS

Several partners are delivering content from our platform directly to their end-users via their own mobile application or website. See our What is a partner network and how do I become one? for an overview and requirements.

This page looks at the technical details of using our RSS feeds to integrate content from our platform into your application. This will allow you to follow content updates from our site and make the audio episodes (with their metadata) available to your end-users.

Why RSS ?

RSS is a well known and documented standard, widely in use, with a massive collection of third-party libraries available for rapid integration. RSS also allows extensibility with additional namespaces, some of which we implement already. 

How do I get the RSS feeds and what does it contain?

Each content creator (eg radio station or podcaster) is registered as a provider on our site, with each of them publishing audio episodes to one or more channels (with each channel typically being one show) 

We currently expose 3 types of RSS feeds:

  • Channel episodes - exposes only episodes published to a specific channel.
  • Provider episodes - a unified list of episodes published to all channels belonging to a provider.
  • Provider channels - a helper RSS feed that lists all the channels available to a provider. This can be used by clients to build a list of available channels.

Channel episodes feed

Channel feeds contain it's active episodes and is updated as new episodes are added to it. The RSS URL for each channel is available using the "Follow as RSS" link on the channel webpage.

For example this channel page links to this RSS URL:
The returned feed contains one item per episode with metadata as standard RSS and the additional iTunes RSS namespace. The audio file location is specified in the enclosure field, for example:
url=";download=1" length="19949825" type="audio/mpeg" />  
Note: your mobile application or the end-user web browser must use this file location directly and 'as is' without centralised caching, as per our Partner network terms.

Provider episodes feed

Every provider also exposes a unified RSS feed that consolidates episodes from all it's channels, allowing you to follow content from the entire range of shows with one feed. This URL can be found on the provider webpage as the "Follow as RSS" link.

For example this provider page links to this RSS URL:
Note that each episode item contains the RSS <source> field which links to the channel that episode belongs to, allowing applications to organise content from this feed on a per-channel basis also, should this be desired. 

Provider channels feed

This feed allows applications to get a list of all active channels available to a provider for completely dynamic applications. To access to this feed, use the same URL as for the provider episodes feed, but append a /channels section to the end.

The URL from the previous example becomes:
Note the <source> field in each channel item matches the value provided for episode items in the other feeds, allowing easy matching and organisation of episodes. 

Limiting RSS content

All RSS feeds are by default hard-limited to a maximum of 60 items. This limit can never be increased but frequently a lot less may be required by your application. You can use the "limit" URL query parameter to reduce the number of items returned for smaller and faster response.

Using the provider example above to get only the first 15 items:
Note that the minimum limit is 10 items!

Paginating RSS content

For applications that require more than 60 items, pagination can be performed by using the skip URL parameter. (Which can be used in combination with the limit parameter.) The skip parameter specifies an offset into the list of results, so for example setting skip to 5 would skip the first 5 items that would normally be returned and start with item 6.

For example getting the first 90 results of a feed, but in 3 pages of 30 items each:
Note that this is available for the episode and channel feeds.

Changing audio quality level

All our media files are made available in various quality levels. (See this article for the list of quality levels and their respective sizes)

By default all RSS feeds return links to the medium quality versions, as this provides the best balance between file size and perceived audio quality. This can be changed using the q URL parameter. For example getting the low quality versions in a providers feed:
Valid options are: low, medium, high, hifi.
Note that the actual levels available are dependant on the provider. If the feed requests a quality level that is not available, the RSS will return the next highest available level.   

Tracking downloads to your application

Applications should use a custom User-Agent string to identify themselves. User-Agent (UA) is a standard header sent with every HTTP request.

For example, the two popular podcast applications Overcast and Podcast Addict use these as their UA header strings:
Overcast/2.0 (+; iOS podcast app)
PodcastAddict/v2 - Dalvik/2.1.0 (Linux; U; Android 6.0.1; Moto G Play Build/MPI24.241-2.35-1.5)
Our analytics engine recognises these two user agents and this enables us to list all audio requests that with these headers to be assigned to the right application. 

When developing your own mobile application, provide us with the UA string your application will be using to retrieve the audio data and we can add this to our analytics engine.

Some notes on implementing your custom User-Agent string:

- The platform and device is also extracted from the User-Agent string if possible, therefore it is recommended to include these details. For example, if your mobile application is available on Android and iOS, the UA string should indicate which platform it is running on.
- It is recommended to include these fields in your application: (a) your application name (b) the version of the application (c) the platform it's running on (d) the device class it's running on.

For example: 

Version 2.1 of the iOS version of your application running on an iPad:
MyApplicationName/v2.1 (iOS, iPad)
Version 1.3 of the Android version of your application:
MyApplicationName/v1.3 (Android)
In the first case our engine would be able to determine that the request is coming from a 'tablet'. (By recognising the "iPad" string). In the second case our engine would only know that it's an Android request and due to lack of more information assume the request is from a 'mobile'.

Feedback and Knowledge Base