Overview
OPML is a simple representation of hierarchical data in XML. The specification may be found here
Our OPML implementation offers a comprehensive view of our directory, with intelligent organization and rich metadata wrapped in an accessible, REST-style API. It is ideally suited to applications needing a “browse tree” of radio content, such that users may drill in to specific stations or shows from a well-defined starting point. For example:
- Music Radio
- Classic Rock
- Featured Stations
- KZPS
- WCBS
Basics
The OPML API is conceptually a web service, but it is not SOAP-based and does not require a web service stack.
An OPML request is nothing more than a URL with certain query string parameters. For example:
# Grab the root menu
GET http://opml.radiotime.com/Browse.ashx
# Browse local radio (geo-detection)
GET http://opml.radiotime.com/Browse.ashx?c=local
# Browse the talk radio tree
GET http://opml.radiotime.com/Browse.ashx?c=talk
# Tune into NPR's Fresh Air
GET http://opml.radiotime.com/Tune.ashx?c=pbrowse&id=p17
There are several “global” parameters that affect the behavior of the service, and when present will be appended to all response links. They are:
| Parameter | Required | Purpose | Values |
|---|---|---|---|
| partnerId | Strongly recommended | Identifies your application as a client of the API. See the getting started guide for details | Provided on registration |
| username | No | Identifies a specific RadioTime user as a client of the API. Allows access to presets and other account features | Created by the user on http://radiotime.com |
| serial | No | Identifies a client of the API from the perspective of the application they are using | See the security model for details |
| formats | No | A comma-separated list of stream media types your application supports. Allows you to tailor the stations and shows that are filtered or displayed by their stream compatibility | See the streaming section below |
| locale | No | An ISO-639/ISO-3166 combination to override the HTTP Accept-Language header | en-US, es, etc |
| latlon | No | A specific latitude/longitude pair, comma separated, used to target local radio | 37.777228,-122.419281 |
OPML responses are XML documents with outline elements and optional metadata. The root menu response, for example, looks like this:
<opml version="1">
<head>
<status>200</status>
<title>RadioTime</title>
</head>
<body>
<outline type="link" text="Local Radio" URL="http://opml.radiotime.com/Browse.ashx?c=local"/>
<outline type="link" text="Browse Talk" URL="http://opml.radiotime.com/Browse.ashx?c=talk"/>
<outline type="link" text="Browse Sports" URL="http://opml.radiotime.com/Browse.ashx?c=sports"/>
<outline type="link" text="Browse Music" URL="http://opml.radiotime.com/Browse.ashx?c=music"/>
<outline type="link" text="Browse Location" URL="http://opml.radiotime.com/Browse.ashx?id=r0"/>
<outline type="link" text="Browse Podcasts" URL="http://opml.radiotime.com/Browse.ashx?c=podcast"/>
<outline type="link" text="My Presets (Please Sign In)" URL="http://opml.radiotime.com/Register.aspx"/>
</body>
</opml>
Streams
To control which stream types are returned by the API, specify the formats query string parameter. The following values are recognized:
| Format Value | Description |
|---|---|
wma |
WMAudio v8/9/10 |
mp3 |
standard MP3 |
aac |
AAC and AAC+ |
real |
Real Media |
flash |
FLV and RTMP |
html |
Usually desktop players |
wmpro |
Windows Media Professional |
wmvoice |
Windows Media Voice |
wmvideo |
Windows Media Video v8/9/10 |
ogg |
Ogg Vorbis |
qt |
Quicktime |
The streams delivered by Tune calls typically use a playlist. The playlist type is chosen based on the client (we can tailor to your capabilities) and the stream itself. By default we’ll serve a basic M3U.
In many cases our playlist will contain multiple streams, with the order chosen by factors including compatibility, reliability, and richness. In the event any stream in the playlist fails, your player should try the next in sequence.