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:
http://iono.fm/rss/chan/2019The 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:
<enclosureNote: 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.
url="http://dl.iono.fm/epi/prov_97/epi_152976.mp3?client=rss&download=1" length="19949825" type="audio/mpeg" />
Tracking your downloads
Registered partner networks are provided with a custom client code to include with each RSS request. Using this code allows us to create a report of content consumed only via your network or application. To use the client code, simply append it as a URL query parameter when requesting the RSS feed. For example, using a client code of "cloud9" with a channel RSS feed URL:
http://iono.fm/rss/chan/2019?client=cloud9All the enclosure fields in the returned RSS now contains the same query parameter in the enclosure fields, allowing our content servers to track your requests. Our platform will ignore any client codes that have not been registered.
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:
http://iono.fm/rss/prov/192Note 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:
http://iono.fm/rss/prov/192/channelsNote 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:
http://iono.fm/rss/prov/192?client=cloud9&limit=15Note 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:
http://iono.fm/rss/prov/192?client=cloud9&limit=30 http://iono.fm/rss/prov/192?client=cloud9&limit=30&skip=30 http://iono.fm/rss/prov/192?client=cloud9&limit=30&skip=60Note 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:
http://iono.fm/rss/prov/192?client=cloud9&q=lowValid 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.