Summary
The browse method produces navigation and audio content from our radio directory. It covers several different structures – presets, popular channels, locations – that are distinguished by an input browse classifier.
All versions of the Browse method accept (and in some cases require) the global variables for OPML.
Browse Index
When invoked without a classifier, the browse method returns a list of the available navigation structures. We strongly recommend you use this index as a “launch” point and follow the navigation links provided, rather than deep linking to an internal browse URL.
Input
GET http://opml.radiotime.com/Browse.ashx
Output
<opml version="1">
<head>
<title>RadioTime</title>
<status>200</status>
</head>
<body>
<outline type="link" text="Local Radio" URL="http://opml.radiotime.com/Browse.ashx?c=local" key="local"/>
<outline type="link" text="Talk" URL="http://opml.radiotime.com/Browse.ashx?c=talk" key="talk"/>
<outline type="link" text="Sports" URL="http://opml.radiotime.com/Browse.ashx?c=sports" key="sports"/>
<outline type="link" text="Music" URL="http://opml.radiotime.com/Browse.ashx?c=music" key="music"/>
<outline type="link" text="By Location" URL="http://opml.radiotime.com/Browse.ashx?id=r0"/>
<outline type="link" text="By Language" URL="http://opml.radiotime.com/Browse.ashx?c=lang" key="language"/>
<outline type="link" text="Podcasts" URL="http://opml.radiotime.com/Browse.ashx?c=podcast" key="podcast"/>
<outline type="link" text="My Presets (Please Sign In)" URL="http://opml.radiotime.com/Register.aspx" key="presets"/>
</body>
</opml>
Browse Local
Creates a list of radio stations local to the caller. Behavior varies by the input available. In the absence of an override our service will use IP geo-location to create its result.
Input
GET http://opml.radiotime.com/Browse.ashx?c=local
| Parameter | Description |
|---|---|
| c | Set to local for this call |
| username | When provided, stations are based on the location defined by the account. Account location settings are managed on radiotime.com |
| latlon | When provided, stations are based on proximity to the geo-coordinate. If the coordinate is in the US, results will be similar to a zipcode search |
| formats | A comma-separated list of compatible stream formats. See the overview for more details |
Output
A complete list of outline elements for stations in the discovered location. If the location maps to an area with sub-locations (like a country), the child elements will be links to those sub-locations.
Notes
If your application proxies client calls, you may forward the originating address in an HTTP header labeled “X-Forwarded-For”.
The latlon parameter has precedence over any others; if specified, it will be used ahead of any user-associated region or IP detection.
Browse Presets
Either a valid RadioTime username or an authorized serial number is required. The service will offer either a list of items (if there is a single preset folder), or a list of folders. Please see the Preset API method for more information on managing presets.
Input
# Gets presets for a named account
GET http://opml.radiotime.com/Browse.ashx?c=presets&username=radiotime
# Gets presets for an anonymous device account
GET http://opml.radiotime.com/Browse.ashx?c=presets&serial=123456
| Parameter | Description |
|---|---|
| c | Set to presets for this call |
| partnerId | Required for this call |
| username | Required if no serial; set to the account whose presets you wish to browse |
| serial | Required if no userName; maps a unique client to an anonymous RadioTime account |
| formats | A comma-separated list of compatible stream formats. See the overview for more details |
Output
If the account has a single preset folder, results will be returned directly. Otherwise, you will receive navigable links for each folder.
Notes
This call is restricted to valid partner IDs – it cannot be invoked anonymously.
Browse Categories
We organize our content into a few broad divisions. They are returned as part of the index menu but may also be addressed directly. For example:
# Fetch the talk radio menu
GET http://opml.radiotime.com/Browse.ashx?c=talk
Input
The following values are valid for the input parameter c:
| Category | URL |
|---|---|
| Music | http://opml.radiotime.com/Browse.ashx?c=music |
| Talk | http://opml.radiotime.com/Browse.ashx?c=talk |
| Sports | http://opml.radiotime.com/Browse.ashx?c=sports |
| World | http://opml.radiotime.com/Browse.ashx?c=world |
Additionally, all the global parameters apply.
Output
Navigable sub-categories for the given category
Notes
The links returned by this method are themselves deeper-level category browsing calls, which will contain groups of stations and shows. By default we return configured page sizes of results in these groups (10 for shows, 50 for stations). Contact RadioTime development if you would like to customize these values.
The world channel is appropriate for finding a specific location by navigating countries, states, and cities.
Browse Language
RadioTime offers radio content from around the world, which means we tag stations and shows in hundreds of languages. The browse language option offers an easy way to filter to a specific language.
Input
# Fetch the root language menu
GET http://opml.radiotime.com/Browse.ashx?c=lang
# Fetch a genre only for Spanish
GET http://opml.radiotime.com/Browse.ashx?c=lang&filter=l99
Output
Without the filter parameter, the service will return a list of languages available in the guide. From that point forward the experience is like a regular category browse, with content narrowed to stations and shows matching the language.
Browse a Station
We maintain station recommendations for many of the stations in our guide. This method makes it possible to browse this content.
Input
GET http://opml.radiotime.com/Browse.ashx?id=s32500
| Parameter | Description |
|---|---|
| id | Set to the guide ID of the station |
| detail | May be set to affiliate, genre, recommendation, or a combination of these three separated by commas (like “affiliate,genre”). When set, the service will return only the specified groups of content |
There is no classifier needed for this call.
Output
If no detail parameter is provided, a list of stations similar to the given station, plus links for the station’s genre and affiliates. Otherwise, the specific requested groups of content.
Browse Station Schedules
For those stations for which we maintain show schedules, you may browse a complete list for the current day or a specified date range.
Input
GET http://opml.radiotime.com/Browse.ashx?c=schedule&id=s32500
| Parameter | Description |
|---|---|
| c | Set to schedule for this call |
| id | Set to the guide ID of the station |
| username | A RadioTime account name; will affect the time zone of the response lineup |
| start | The start date for the lineup, in form yyyymmdd |
| stop | The end date for the lineup, in form yyyymmdd |
| forward | When set to true, the service will ignore the start and stop dates and instead provide a schedule looking forward over the next 24-36 hours. Also see the live parameter |
| live | When using the forward parameter, setting live to true will include the currently live show in the result. Otherwise the service will return the lineup starting with the show next on. |
To retrieve a specific day, you may omit the stop date. The service currently limits each request to a maximum of 3 days.
Output
A list of shows in chronological order, with start times in either the user time zone (if a username is supplied) or UTC. Each show will have an outline element like the following:
<outline type="link" text="Science in Action" URL="http://opml.radiotime.com/Browse.ashx?c=topics&id=p440&title=Science+in+Action" guide_id="p440" start="2009-03-16T00:06:00" duration="1440" image="http://radiotime-logos.s3.amazonaws.com/p440q.png" tz="Central"/>
The duration attribute is in seconds. The URL may be used to tune the show if it is currently broadcasting, or if it has previous topics available for listening. The tz attribute gives the descriptive name of the user time zone, if a username is supplied.