SHOUTcast Radio Directory API

2011-03-21T17:24:57Z

Radio Palermo: /* Get Stations by Keyword Search */

=Get Stations on SHOUTcast Radio Directory=

==Get Top 500 Stations==
'''Description:''' Get top 500 stations on SHOUTcast Radio directory.

'''URL:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]</nowiki>

'''Required Parameters:'''
* k - API Dev Key.

'''Optional Parameters:'''
* limit - Limit the number of stations to return by passing the limit parameter.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&limit=5</nowiki>

'''Sample XML Response:''' (with limits)
<stationlist>
<tunein base="/sbin/tunein-station.pls"/>
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"
genre="Pop Rock Top 40"ct="The Fray - You Found Me" lc="4670"/>
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]"
mt="audio/mpeg" id="120149" br="24" genre="Malaysia
Malay" ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/>
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"
mt="audio/mpeg" id="1264" br="96" genre="Soft Smooth Jazz"
ct="Oli Silk - De-stress Signal" lc="3507"/>
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill"
ct="Verbrilli Sound - Descender" lc="2680"/>
<station name=".977 The 80s Channel-[SHOUTcast.com]" mt="audio/mpeg" id="6803"
br="128" genre="80s Pop Rock" ct="Starship - Nothing`s gonna stop us now (1987)" lc="2192"/>
<station name="The Alex Jones Show-[SHOUTcast.com]" mt="audio/mpeg" id="5516" br="32" genre="Talk"
ct="Refeed: Hour 1 (Listen by phone 512-646-5000)" lc="1987"/>
</stationlist>

==Get Stations by Keyword Search==
'''Description:''' Get stations which match the keyword searched on SHOUTcast Radio Directory.
:'''Note:''' This API returns stations which has keyword match in the following fields Station Name, Now Playing info, Genre.

'''URL:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats</nowiki>

'''Required Parameters:'''
* search - Specify the query to search.
* k - API Dev ID.

'''Optional Parameters:'''
* limit - Limits the no of results to be returned.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=10</nowiki>

* limit with pagination - Limits the no of results with pagination included.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=X,Y</nowiki>
:* Y is the number of results to return and X is the offset.

* Filter by Codec type - Get stations which match the codec type requested.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&mt=audio/mpeg</nowiki>
:MP3 = audio/mpeg and AAC+ = audio/aacp

'''Sample XML Response:'''
<stationlist>
<tunein base="/sbin/tunein-station.pls"></tunein>
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="241">
</station>
<station name="((Metaphoric.me))128k Room42, ambient beats and chill grooves-[SHOUTcast.com]"
mt="audio/mpeg" id="8434" br="128" genre="Ambient Chill" ct="Jazz City - La Noche (Smooth Latin Groove Mix)" lc="83">
</station>
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
mt="audio/mpeg" id="8010" br="24" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="54">
</station>
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
mt="audio/mpeg" id="9073" br="56" genre="Ambient Chill" ct="Warheads - Daphne" lc="30">
</station>
</stationlist>

==Get Stations by Genre==
'''Description:''' Get stations which match the genre specified as query.

'''URL:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic</nowiki>

'''Required Parameters:'''
* k - API Dev ID.

'''Optional Parameters:'''
* limit - Limits the no of results to be returned.

* limit with pagination - Limits the no of results with pagination included.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&limit=X,Y</nowiki>
:* Y is the number of results to return and X is the offset.

* Filter by Codec type - Get stations which match the codec type requested.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&&mt=audio/aacp</nowiki>
:MP3 = audio/mpeg and AAC+ = audio/aacp.

'''Sample XML Response:'''
<stationlist>
<tunein base="/sbin/tunein-station.pls"/>
<station name=".977 The Hitz Channel-[SHOUTcast.com]" mt="audio/mpeg" id="9907" br="128"
genre="Pop Rock Top 40" ct="The Fray - You Found Me" lc="4670"/>
<station name="HOT FM - Lebih Hangat Daripada Biasa : HOT fm-[SHOUTcast.com]" mt="audio/mpeg"
id="120149" br="24" genre="Malaysia Malay"
ct="LELAKI IDAMAN MELLY_GOESLOW " lc="3961"/>
<station name="S K Y . F M - Absolutely Smooth Jazz - the world's smoothest jazz 24 hours a day-[SHOUTcast.com]"
mt="audio/mpeg" id="1264" br="96" genre="Softsmooth Jazz"
ct="Oli Silk -De-stress Signal" lc="3507"/>
<station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
mt="audio/mpeg" id="6687" br="128" genre="AmbientChill"
ct="Verbrilli Sound - Descender" lc="2680"/>
</stationlist>

==Get Stations Based on Now Playing Info==
'''Description:''' Return stations which match a specified query in the now playing node.

'''URL:'''
<nowiki>http://api.shoutcast.com/station/nowplaying?k=[Your Dev ID]&ct=rihanna&f=xml</nowiki>

'''Required Parameters:'''
* ct - Query to search in Now Playing node.
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).
* limit - Limits the no of results to be returned in output.

'''Sample XML Response:'''
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationlist>
<tunein base="/sbin/tunein-station.pls"/>
<station name="Dj Wouner- Radio Fusion-A novidade come?a Aqui!-[SHOUTcast.com]" mt="audio/mpeg" id="139549"
br="64" genre="Various"ct="Rihanna Feat. Chris Brown & Jay-Z - Umbrella" lc="614" ml="2100" nsc="No"/>
<station name="R?dio Stronda [ Digital ] Servidor 4-[SHOUTcast.com]" mt="audio/mpeg" id="998783" br="64"
genre="Pop Top Rock Funk Str"ct="T.I. feat Rihanna -Live Your Life" lc="243" ml="70" nsc="No"/>
.
.
</stationlist>
</data>
</response>

'''URL (JSON Request):'''

<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner-
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","lc":"614","ml":"2100","br":"64",
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor
4-[SHOUTcast.com]","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},
.
.
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Various","id":"139549","mt":"audio/mpeg","name":"Dj Wouner-
RadioFusion-A novidadecome?a Aqui!-[SHOUTcast.com]","lc":"614","ml":"2100","br":"64",
"ct":"Rihanna Feat. Chris Brown& Jay-Z - Umbrella"},
{"nsc":"No","genre":"Pop Top Rock Funk Str","id":"998783",
"mt":"audio/mpeg","name":"R?dio Stronda[ Digital ] Servidor
4-[SHOUTcast.com]","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},
.
.
]
}
}
}
)

==Get Stations by Bitrate or Codec Type==
'''Description:''' Get stations which match a particular bitrate or codec type.

'''URL:'''
:* Stations filtered by bitrate
::<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=10&f=xml&k=[Your Dev ID]</nowiki>

:* Stations filtered by media type
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&limit=10&f=xml&k=[Your Dev ID]</nowiki>

:* Stations filtered by bitrate, media type & genre
::<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=audio/mpeg&br=128&search=Trance&&limit=10&f=xml&k=[Your Dev ID]</nowiki>

'''Required Parameters:'''

* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.
* br - Filter the stations based on bitrate specified.
* mt - Filter the stations based on media type specified.

'''Optional Parameters:'''

* c - The callback function to invoke in the response (appropriate for JSON responses only).
* limit - Limits the no of results to be returned in output.
* genre - Filter stations that match the genre passed.

'''Sample XML Response:'''
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationlist>
<tunein base="/sbin/tunein-station.pls"/>
<station name=".977 The Hitz Channel" mt="audio/mpeg" id="9907"
br="128" genre="Pop Rock Top 40"
ct="Chingy - Balla Baby" lc="11576"/>
<station name="TechnoBase.FM - 24h Techno, Dance, Trance, House and More - 128k MP3-[SHOUTcast.com]"
mt="audio/mpeg"id="7429" br="128"genre="Techno Trance Dance House"
ct="We aRe oNe" lc="8308" ml="8500" nsc="No"/>
<station name="Absolutely Smooth Jazz - S K Y . F M - the world's smoothest
jazz 24 hours a day-[SHOUTcast.com]" mt="audio/mpeg" id="948"br="96" genre="Soft Smooth Jazz"
ct="Jonathan Butler/Kirk Whalum - Dancing on the Shore" lc="6801" ml="10023" nsc="No"/>
.
.
</stationlist>
</data>
</response>

'''URL (JSON Request):'''
* Stations based on bitrate
:<nowiki>http://api.shoutcast.com/station/advancedsearch?br=128&limit=3&f=json&k=[Your Dev ID]</nowiki>

* Stations based on media type
:<nowiki>http://api.shoutcast.com/station/advancedsearch?mt=mpeg&limit=3&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The
HitzChannel-[SHOUTcast.com]","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},
{"nsc":"No","genre":"Techno Trance
DanceHouse","id":"7429","mt":"audio/mpeg",
"name":"TechnoBase.FM - 24h
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308","ml":"10023",
"br":"128","ct":"We aRe oNe"},
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's
smoothest jazz 24hours a day-[SHOUTcast.com]","lc":"6801","ml":"18600","br":"96",
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},
.
.
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Pop Rock Top 40","id":"9907",mt":"audio/mpeg","name":".977 The
HitzChannel-[SHOUTcast.com]","lc":"11576","ml":"8500","br":"128","ct":"Chingy - Balla Baby"},
{"sc":"No","genre":"Techno Trance
DanceHouse","id":"7429","mt":"audio/mpeg",
"name":"TechnoBase.FM - 24h
Techno, Dance,Trance, House and More -128kMP3-[SHOUTcast.com]","lc":"8308",
"ml":"10023","br":"128","ct":"We aRe oNe"},
{"nsc":"No","genre":"Soft Smooth Jazz","id":"948","mt":"audio/mpeg",
"name":"Absolutely Smooth Jazz - S K Y . F M - the world's
smoothest jazz 24hours a day-[SHOUTcast.com]","lc":"6801","ml":"18600","br":"96",
"ct":"Jonathan Butler/Kirk Whalum - Dancing on the Shore"},
.
.
]
}
}
}
)

==Get Random Stations==
'''Description:''' Get random stations on SHOUTcast Radio Directory. Random stations can be restricted to the Bitrate/Genre/Media type specified.

'''URL:'''

:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml</nowiki>
::Returns a random station. This API by default returns one random station.
::To get more random stations, set the number of stations to return by passing the limit parameter.

:* <nowiki>http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml&mt=audio/mpeg&br=128&genre=Fresh</nowiki>
::Returns a random station. This API by default returns one random station.
::To get more random stations, set the number of stations to return by passing the limit parameter.

'''Required Parameters:'''
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).
* br - Bitrate to filter the station result.
* mt - Media type to filter the station result.
* genre - Genre to filter the station result.
* limit - This API by default returns one station. To get more random stations, set the number of stations to return by passing the limit parameter.

'''Sample XML Response:'''(Parameter Limit)
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<stationlist>
<tunein base="/sbin/tunein-station.pls"/>
<station name="FreshBakedJams.com-[SHOUTcast.com]" mt="audio/mpeg" id="429395" br="128" genre="Fresh BakedJams"
ct="D-Rellz - Story" lc="0" ml="600" nsc="No"/>
</stationlist>
</data>
</response>

'''URL (JSON Request):'''

<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"},
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"stationlist":{
"station":[
"tunein":{
"base":"/sbin/tunein-station.pls"
}
{"nsc":"No","genre":"Turkish TurkTurkce","id":205936,"mt":"audio/mpeg",
"name":"TRD 1 - Turk Radyo Dunyasi - Turkish World
Radio - SMS: +90 544 644 6226- www.trd.com.tr-[SHOUTcast.com]",
"lc":2,"ml":"600","br":32,"ct":"Nalan -Sonunda Bitti"},
]
}
}
}
)

=Get Genres on SHOUTcast Radio Directory=

==Get All Genres==
'''Description:''' Get all the genres on SHOUTcast Radio Directory

'''URL:''' <nowiki>http://api.shoutcast.com/legacy/genrelist?k=[Your Dev ID]</nowiki>

'''Required Parameters:'''
* k - API Dev ID.

'''Sample XML Response:'''

<genrelist>
<genre name="30s"/>
<genre name="40s"/>
<genre name="50s"/>
<genre name="60s"/>
<genre name="70s"/>
<genre name="80s"/>
<genre name="90s"/>
.
.
</genrelist>

==Get Primary Genres==
'''Description:''' Get only the Primary Genres on SHOUTcast Radio Directory

'''URL:''' <nowiki>http://api.shoutcast.com/genre/primary?k=[Your Dev ID]&f=xml</nowiki>

'''Required Parameters:'''

* f - the response format (xml, json,rss). You can choose xml, json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).

'''Sample XML Response:'''
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<genrelist>
<genre name="Alternative" id="1" parentid="0" haschildren="true"/>
<genre name="Blues" id="24" parentid="0" haschildren="true"/>
.
.
.
</genrelist>
</data>
</response>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},
{"id":24,"haschildren":true,"name":"Blues","parentid":0},
.
.
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},
{"id":24,"haschildren":true,"name":"Blues","parentid":0},
.
.
]
}
}
}
)

==Get Secondary Genres==
'''Description:''' Get secondary genre list (if present) for a specified primary genre.

'''URL:''' <nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&k=[Your Dev ID]&f=xml</nowiki>

'''Required Parameters:'''
* parentid - Genreid of the primary genre. You can retreive the entire genre set by passing parentid=0.
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).

'''Sample XML Response:'''
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<genrelist>
<genre name="Alternative" id="1" parentid="0" haschildren="true">
<genrelist>
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/>
<genre name="Britpop" id="3" parentid="1" haschildren="false"/>
<genre name="Classic Alternative" id="4" parentid="1" haschildren="false"/>
.
.
</genrelist>
</genre>
</genrelist>
</data>
<response>

'''URL (JSON Request):'''

<nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
"genrelist":{
"genre":[
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},
{"id":24,"haschildren":true,"name":"Blues","parentid":0},
{"id":32,"haschildren":true,"name":"Classical","parentid":0},
.
.
]
}
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
"genrelist":{
"genre":[
{"id":1,"haschildren":true,"name":"Alternative","parentid":0},
{"id":24,"haschildren":true,"name":"Blues","parentid":0},
{"id":32,"haschildren":true,"name":"Classical","parentid":0},
.
.
]
}
]
}
}
}
)

==Get Genres Details by Passing Genreid==
'''Description:''' Get details such as Genre Name, Sub Genres (if its a primary genre), has children by passing the genre-id.

'''URL:''' <nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=xml&k=[Your Dev ID]</nowiki>

'''Required Parameters:'''
* id - Input respective genre or sub-genre id.
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).

'''Sample XML Response:'''
<response>
<statusCode>200 </statusCode>
<statusText>Ok </statusText>
<data>
<genrelist>
<genre name="Acoustic Blues" id="25" parentid="24" haschildren="false"/>
</genrelist>
</data>
</response>

'''URL (JSON Request):'''

<nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":{
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}
}
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":{
{"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}
}
}
}
}
)

==Get Genres Based on Availability of Sub-Genres==
'''Description:''' Get genres based on their sub-genre availability at any node level in the genre hierarchy of SHOUTcast.

'''URL:'''
:*Genres with sub genres:
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=xml&k=[Your Dev ID]</nowiki>

:*Genres without sub genres:
::<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=false&f=xml&k=[Your Dev ID]</nowiki>

'''Required Parameters:'''
* haschildren
:* 'true' to get genre or subgenre which has sub-genres.
:* 'false' to get genre or subgenre which does not have sub-genres.
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
* k - API Dev ID.

'''Optional Parameters:'''
* c - The callback function to invoke in the response (appropriate for JSON responses only).

'''Sample XML Response:'''
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<genrelist>
<genre name="Alternative" id="1" parentid="0" haschildren="true"/>
<genrelist>
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/>
<genre name="Britpop" id="3" parentid="1" haschildren="false"/>
.
.
</genrelist>
</genre>
<genre name="Blues" id="24" parentid="0" haschildren="true"/>
<genrelist>
<genre name="Adult Alternative" id="2" parentid="1" haschildren="false"/>
<genre name="Britpop" id="3" parentid="1" haschildren="false"/>
.
.
</genrelist>
</genre>
.
.
</genrelist>
</data>
</response>

'''URL (JSON Request):'''

<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=json&k=[Your Dev ID]</nowiki>

'''Sample JSON Response:'''
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
"genrelist":{
"genre":[
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},
{"id":195,"haschildren":true,"name":"Metal","parentid":0},
.
.
]
}
]
}
}
}

'''Sample JSON Response (with callback):'''
callbackfunctionname(
{"response":{
"statusCode":200,
"statusText":"Ok"
},
"data":"{
"genrelist":{
"genre":[
"genrelist":{
"genre":[
{"id":2,"haschildren":false,"name":"AdultAlternative","parentid":1},
{"id":3,"haschildren":false,"name":"Britpop","parentid":1},
{"id":4,"haschildren":false,"name":"ClassicAlternative","parentid":1},
{"id":205,"haschildren":false,"name":"RapMetal","parentid":195},
{"id":195,"haschildren":true,"name":"Metal","parentid":0},
.
.
]
}
]
}
}
}
)

=Other=

==How To Tune Into A Station==

To tune into a station, find the "id" of the station from the API results & make a call to <nowiki>http://yp.shoutcast.com/sbin/tunein-station.pls?id=[Station_id]</nowiki> by appending the station id.

'''Ex:''' If the station id is 1025, Call => <nowiki>http://yp.shoutcast.com/sbin/tunein-station.pls?id=1025&k=[Your Dev ID]</nowiki>

==XML Caching==

Do not cache the XML for more than 1 day, as station ID's can and will change.

==Error Codes==

The Error codes encountered when invalid data is input or passed to access the APIs are as below

'''HTTP Status Code'''

:400=Bad Request

:404=Page Not Found

:500=Generic Server Error

:460=Missing required parameter

:462=Parameter Error

:440=Invalid Devid

'''BUSINESS_ERROR'''

:10001=Internal Server error

:10002=XML Root Element not matching

:10003=Error while interacting with private api

:10002=Cache xml data not found

'''GENERAL_ERROR'''

:20001=Unable to find InitialContext

:20002=Unable to acquire DataSource

:20003=Unable to load SQL query

:20004=Unable to load property file

:20005=Unable to execute SQL query

:20006=Unable to fetch ResultSet

:20007=Error in finally block

:20008=NullPointer Exception Raised

:20009=Error while adding xml element

:20010=Number Format Exception

:20011=Error in creating xml document

:20012=Null object received

:20012=XML Data not found in Cache

:20013=File not found

:20014=Unable to connect to search api

:20015=Error while building xml document

:20016=Error while encoding url string

:20017=Error while connecting to shoutcast api

:20018=Error while processing the jsp

:20019=Error while reading request object

:20020=Error while sending email

:20021=Invalid Response Type

:20022=Maximum Value Exceeded

:20023=Error while connecting to AKES

:20024=Error while building AKES response xml document

:20025=No Data in AKES response xml document

:20026=Missing required parm : (REFERRER)

:20027=Invalid key received from

:20028=Missing devId= or k= param

:20029=Missing required parm : (k)

:20030=Missing required parm : (keyType)

:20027=Deny - authRequired fail

:20028=Deny - usageLimited fail

:20029=Deny - rightNotSet fail

:20030=Deny - referrerUsageLimited fail

Winamp Developer Wiki - User contributions [en]

SHOUTcast Radio Directory API