Difference between revisions of "SHOUTcast Developer"

From Winamp Developer Wiki
Jump to: navigation, search
(New page: =Get Stations on SHOUTcast Radio Directory= ==Get Top 500 Stations== '''<span style="color:#FF6600;">Description:</span>''' Get top 500 stations on SHOUTcast Radio directory. '''<span st...)
 
m (Fixed old link)
 
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=Get Stations on SHOUTcast Radio Directory=
+
{{Template:NavBarSC}}
  
==Get Top 500 Stations==
 
'''<span style="color:#FF6600;">Description:</span>''' Get top 500 stations on SHOUTcast Radio directory.
 
  
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]</nowiki>
+
Here you can find some of the technical documentation about some of the Shoutcast system from accessing the Shoutcast Radio Directory to the streaming protocol used as well as some legacy information for historical purposes.
  
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
::'''[[SHOUTcast_API_License_Agreement|Shoutcast API Usage Restrictions and Logos]]'''
* k - API Dev Key.
+
  
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
::'''[https://www.shoutcast.com/Partners API Partner Applications (How and Where to Request a DevID Key)]'''
* 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>
+
  
'''<span style="color:#FF6600;">Sample XML Response:</span>''' (with limits)
+
::'''[[SHOUTcast_Radio_Directory_API|Shoutcast Radio Directory Partner API Documentation]]''' - Reference for accessing information from the Radio Directory
<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>
+
  
 +
::'''[[SHOUTcast_Radio_Authhash_API|Shoutcast Radio Authhash Partner API Documentation]]''' - Reference for accessing the Shoutcast 2 Authhash Management API
  
==Get Stations by Keyword Search==
+
::'''[[SHOUTcast_2_%28Ultravox_2.1%29_Protocol_Details|Shoutcast / Ultravox 2.1 Protocol Details]]''' - Reference for anyone wanting to implement clients or servers supporting the Shoutcast 2 protocol
'''<span style="color:#FF6600;">Description:</span>''' 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.
+
  
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats</nowiki>
+
::'''[[SHOUTcast_XML_Metadata_Specification|Shoutcast XML Metadata Specification]]'''
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* search - Specify the query to search.
+
* k - API Dev ID.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* 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
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match the genre specified as query.
+
 
+
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* k - API Dev ID.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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==
+
'''<span style="color:#FF6600;">Description:</span>''' Return stations which match a specified query in the now playing node.
+
 
+
'''<span style="color:#FF6600;">URL:</span>'''
+
<nowiki>http://api.shoutcast.com/station/nowplaying?k=[Your Dev ID]&ct=rihanna&f=xml</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
 
+
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"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"},
+
    .
+
    .
+
    ]
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get stations which match a particular bitrate or codec type.
+
 
+
'''<span style="color:#FF6600;">URL:</span>'''
+
:* 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>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
 
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
 
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
* 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>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"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"},
+
    .
+
    .
+
    ]
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get random stations on SHOUTcast Radio Directory. Random stations can be restricted to the Bitrate/Genre/Media type specified.
+
 
+
'''<span style="color:#FF6600;">URL:</span>'''
+
 
+
:* <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.
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* f - the response format (xml, json, rss). You can choose xml,json or rss based results.
+
* k - API Dev ID.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''(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>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
 
+
<nowiki>http://api.shoutcast.com/station/nowplaying?ct=rihanna&f=json&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"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"},
+
    ]
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get all the genres on SHOUTcast Radio Directory
+
 
+
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/legacy/genrelist?k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* k - API Dev ID.
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
 
+
<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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get only the Primary Genres on SHOUTcast Radio Directory
+
 
+
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/primary?k=[Your Dev ID]&f=xml</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
 
+
* f - the response format (xml, json,rss). You can choose xml, json or rss based results.
+
* k - API Dev ID.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* c - The callback function to invoke in the response (appropriate for JSON responses only).
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"response":{
+
  "statusCode":200,
+
    "statusText":"Ok"
+
  },
+
  "data":"{
+
  "genrelist":{
+
    "genre":[
+
    {"id":1,"haschildren":true,"name":"Alternative","parentid":0},
+
      {"id":24,"haschildren":true,"name":"Blues","parentid":0},
+
    .
+
    .
+
    ]
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get secondary genre list (if present) for a specified primary genre.
+
 
+
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&k=[Your Dev ID]&f=xml</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* c - The callback function to invoke in the response (appropriate for JSON responses only).
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
 
+
<nowiki>http://api.shoutcast.com/genre/secondary?parentid=0&f=json&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"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},
+
      .
+
      .
+
      ]
+
    }
+
    ]
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get details such as Genre Name, Sub Genres (if its a primary genre), has children by passing the genre-id.
+
 
+
'''<span style="color:#FF6600;">URL:</span>''' <nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=xml&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* c - The callback function to invoke in the response (appropriate for JSON responses only).
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<response>
+
  <statusCode>200 </statusCode>
+
  <statusText>Ok </statusText>
+
  <data>
+
  <genrelist>
+
    <genre name="Acoustic Blues" id="25" parentid="24" haschildren="false"/>
+
  </genrelist>
+
  </data>
+
</response>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
 
+
<nowiki>http://api.shoutcast.com/genre/secondary?id=25&f=json&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"response":{
+
  "statusCode":200,
+
  "statusText":"Ok"
+
  },
+
  "data":"{
+
  "genrelist":{
+
    "genre":{
+
    {"id":25,"haschildren":false,"name":"AcousticBlues","parentid":24}
+
    }
+
  }
+
  }
+
}
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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==
+
'''<span style="color:#FF6600;">Description:</span>''' Get genres based on their sub-genre availability at any node level in the genre hierarchy of SHOUTcast.
+
 
+
'''<span style="color:#FF6600;">URL:</span>'''
+
:*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>
+
 
+
'''<span style="color:#FF6600;">Required Parameters:</span>'''
+
* 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.
+
 
+
'''<span style="color:#FF6600;">Optional Parameters:</span>'''
+
* c - The callback function to invoke in the response (appropriate for JSON responses only).
+
 
+
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
+
<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>
+
 
+
'''<span style="color:#FF6600;">URL (JSON Request):</span>'''
+
 
+
<nowiki>http://api.shoutcast.com/genre/secondary?haschildren=true&f=json&k=[Your Dev ID]</nowiki>
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
+
{"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},
+
      .
+
      .
+
      ]
+
    }
+
    ]
+
  }
+
  }
+
}
+
 
+
 
+
'''<span style="color:#FF6600;">Sample JSON Response (with callback):</span>'''
+
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
+

Latest revision as of 13:39, 29 November 2021

Shoutcast Home | Shoutcast Server (DNAS) | Shoutcast Developer (API) | Shoutcast For Business & Revenue Generation | Shoutcast DSP (encoder Plug-In for Winamp)


Here you can find some of the technical documentation about some of the Shoutcast system from accessing the Shoutcast Radio Directory to the streaming protocol used as well as some legacy information for historical purposes.

Shoutcast API Usage Restrictions and Logos
API Partner Applications (How and Where to Request a DevID Key)
Shoutcast Radio Directory Partner API Documentation - Reference for accessing information from the Radio Directory
Shoutcast Radio Authhash Partner API Documentation - Reference for accessing the Shoutcast 2 Authhash Management API
Shoutcast / Ultravox 2.1 Protocol Details - Reference for anyone wanting to implement clients or servers supporting the Shoutcast 2 protocol
Shoutcast XML Metadata Specification