Summary
The Describe method offers detailed information about an item in the radio directory in a non-navigable form. This may be useful in constructing a richer user interface after an audio item such as a station or show is reached in navigation.
Callers may request alternate metadata by specifying the query string parameter c. The following metadata are currently available:
Describe NowPlaying
This class returns 2 or more text lines describing the content currently broadcast on a station or stream. The cache-control HTTP response header will indicate the time-to-live, if applicable, so that you may refresh your client display at the appropriate time.
Input
GET http://opml.radiotime.com/Describe.ashx?c=nowplaying&id=s32500
| Parameter | Description |
|---|---|
| c | Set to nowplaying for this call |
| id | Set to the guide ID for which you need information; you can gather this from any previous outline element’s guide_id attribute |
Output
Currently we provide a descriptive station name, show title, and show genre for scheduled programming:
<opml version="1">
<head>
<status>200</status>
</head>
<body>
<outline type="text" text="KERA 90.1" image="http://radiotime-logos.s3.amazonaws.com/p38386q.png" preset_id="s32500"/>
<outline type="text" text="Day to Day"/>
<outline type="text" text="Magazine"/>
</body>
</opml>
Notes
If the station has song coverage in our guide, one of the text elements will be the name and artist associated with the song.
Describe Station
Given only a station ID, the service will return detailed information about the corresponding station. The types of detail may be specified as input.
Input
# Fetch basic metadata for the station
GET http://opml.radiotime.com/Describe.ashx?id=s32500
# Fetch basic metadata, genres, and recommendations
GET http://opml.radiotime.com/Describe.ashx?id=s32500&detail=genre,recommendation
| Parameter | Description |
|---|---|
| id | Set to the guide ID for which you need information; you can gather this from any previous outline element’s guide_id attribute |
| detail | A comma-separated list of values indicating additional detail to retrieve. The allowable options are affiliate, genre, and recommendation, or a comma-separated combination of the three. This parameter is not required |
Output
Will return a single outline element of type object, containing a station. If the detail parameter is specified, the response will also contain the requested groups.
Describe Show
Given only a show ID, the service will return detailed information about the corresponding show.
Input
# Fetch basic metadata for the show
GET http://opml.radiotime.com/Describe.ashx?id=p17
| Parameter | Description |
|---|---|
| id | Set to the guide ID for which you need information; you can gather this from any previous outline element’s guide_id attribute |
| detail | A comma-separated list of values indicating additional detail to retrieve. The allowable options are affiliate, genre, and recommendation, or a comma-separated combination of the three. This parameter is not required |
Output
Will return a single outline element of type object, containing a show. If the detail parameter is specified, the response will also contain the requested groups.
Describe Topic
Retrieves metadata for a single radio show topic.
Input
# Fetch basic metadata for a topic
GET http://opml.radiotime.com/Describe.ashx?id=t31779943
| Parameter | Description |
|---|---|
| id | Set to the guide ID for which you need information; you can gather this from a previous outline element’s guide_id attribute |
Output
Will return a single outline element of type object, containing a topic.
Describe Countries
Retrieves a list of all countries known to the RadioTime directory.
Input
# Fetch all countries
GET http://opml.radiotime.com/Describe.ashx?c=countries
| Parameter | Description |
|---|---|
| c | Set to countries for this call |
Output
A list of outline elements whose guide_id attributes may be used in Search, Browse, and Account calls.