Integration into native apps using RSS

Audio content hosted on our website can be integrated directly into native apps using our extended RSS feeds.

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 via additional namespaces, some of which we implement already.

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

We currently expose several 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.
• Stream line-up from channels - a helper RSS feed uses all the channels available to a provider to assembled a weekly line-up RSS.

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 "Subscribe" link on the channel page.

For example, the channel at https://iono.fm/c/2019 has it's RSS feed at https://iono.fm/rss/chan/2019

The 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:

<enclosure url="https://dl.iono.fm/epi/prov_97/epi_152976_medium.m4a?p=rss" length="304852" type="audio/x-m4a"/>

Provider episodes feed

Every provider 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.

For example, provider page at https://iono.fm/p/192 has it's RSS feed at https://iono.fm/rss/prov/192

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 from a provider to assemble 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.

For example provider RSS at https://iono.fm/rss/prov/192/ becomes https://iono.fm/rss/prov/192/channels

The <source> field in each item matches the value provided for episode items in the other feeds, allowing easy matching and organisation of episodes.

Broadcast schedule feed

Using the "Broadcast schedule" configured for the provider, an RSS feed can provide information on which show is currently playing and the coming schedule for up to a week. To access to this feed, use this URL structure:

https://iono.fm/rss/stream/prov/<provider_id>

• The <channel> part of the RSS feed is populated by data from the provider.
• Client applications can use the <ionofm:stream> element to determine the latest direct streaming URLs.
• Each RSS <item> element specifies a show with it's start time and duration. Each of these corresponds to a channel on our platform.
• The <item> elements are sorted in chronological order, with the first item being either current show or the next one coming up.
• There may be gaps between the the shows, depending on the configuration of the channel schedules.

Each <item> element contains the following fields that can be used by client applications to determine and display the current and next shows:

• The <pubDate> field indicates the start time of the show.
• The <ionofm:endDate> element (as specified in our ionofm namespace) indicates the end of the show.
• The <itunes:duration> element indicates the running time of the show.

Limiting content

All RSS feeds are by default hard-limited to a certain number of items. This limit can never be increased but frequently a lot less may be required by your application. Less data also allows faster display times.

The limit URL query parameter allows changing the number of items returned for smaller and faster response.

Example, get only the first 15 items for a provider: http://iono.fm/rss/prov/192?limit=15.

Limited to a minimum value of 10.

Paginating content

Applications may wish to allow users to browse much older episodes. To allow this a skip URL query parameter can be used in combination with the limit parameter to implement pagination:

For example getting the first 90 results of a feed, but in 3 pages of 30 items each:

http://iono.fm/rss/prov/192?limit=30
http://iono.fm/rss/prov/192?limit=30&skip=30
http://iono.fm/rss/prov/192?limit=30&skip=60

This functionality is only available on episode and channel feeds.

Change audio quality

All our media files are made available in various quality levels.

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.

Example, getting the low quality versions for a channel: http://iono.fm/rss/prov/192?q=low

Valid options quality options for the q parameter are: low, medium, high.

Make the app visible to our analytics

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

Example, the two popular podcast applications Overcast and Podcast Addict use these as their UA header strings:

• Overcast/2.0 (+http://overcast.fm/; 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 enables us to correctly display access from this application to our publishers.

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

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.

We recommended always includin these fields in your application's UA string:

1. Application name
2. Application version
3. The platform it's running on
4. The device class it's running on

Where possible, (3) and (4) should be retrieved realtime from the device and not hard-codec into the string.

Example, version 2.1 of MyApp running on an iPhone 12 using iOS 13: MyApp/v2.1 (iOS 13, iPhone 12)

Version 1.3 of the same app running on an Android device: MyApp/v1.3 (Android 12, Phone Samsung)