Difference between revisions of "SHOUTcast Radio Directory API"

From Winamp Developer Wiki
Jump to: navigation, search
m
(Add missing supported parameters from some of the legacy methods)
 
Line 15: Line 15:
 
* limit - Limit the number of stations to return by passing the limit parameter.
 
* 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>
 
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&limit=5</nowiki>
 +
 +
* br - Filter the stations based on bitrate specified.
 +
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&br=64</nowiki>
 +
 +
* mt - Filter the stations based on media type specified.
 +
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&mt=audio/aacp</nowiki>
 +
:MP3 = audio/mpeg and AAC+ = audio/aacp
 +
  
 
'''<span style="color:#FF6600;">Sample XML Response:</span>''' (with limits)
 
'''<span style="color:#FF6600;">Sample XML Response:</span>''' (with limits)
Line 57: Line 65:
 
:* Y is the number of results to return and X is the offset.  
 
:* 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.
+
* br - Filter the stations based on bitrate specified.
 +
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&br=64</nowiki>
 +
 
 +
* mt - Filter the stations based on media type specified.
 
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&mt=audio/mpeg</nowiki>
 
:'''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
 
:MP3 = audio/mpeg and AAC+ = audio/aacp
 +
  
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
 
<source lang="xml">
 
<source lang="xml">
 
<stationlist>
 
<stationlist>
  <tunein base="/sbin/tunein-station.pls"></tunein>
+
  <tunein base="/sbin/tunein-station.pls"/>
 
  <station name="Groove Salad: a nicely chilled plate of ambient beats and grooves. [SomaFM]-[SHOUTcast.com]"
 
  <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">
 
   mt="audio/mpeg" id="6687" br="128" genre="Ambient Chill" ct="Audiomontage - Abyss" lc="241">
Line 96: Line 108:
 
:* Y is the number of results to return and X is the offset.
 
:* 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.
+
* br - Filter the stations based on bitrate specified.
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&&mt=audio/aacp</nowiki>
+
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&br=64</nowiki>
:MP3 = audio/mpeg and AAC+ = audio/aacp.
+
 
 +
* mt - Filter the stations based on media type specified.
 +
:'''Ex:''' <nowiki>http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&mt=audio/mpeg</nowiki>
 +
:MP3 = audio/mpeg and AAC+ = audio/aacp
 +
 
  
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
Line 133: Line 149:
 
* c - The callback function to invoke in the response (appropriate for JSON responses only).
 
* 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.
 
* limit - Limits the no of results to be returned in output.
 +
* br - Filter the stations based on bitrate specified.
 +
* mt - Filter the stations based on media type specified.
 +
* genre - Filter stations that match the genre passed.
 +
  
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''
Line 210: Line 230:
 
)
 
)
 
</source>
 
</source>
 +
  
 
==Get Stations by Bitrate or Codec Type or Genre ID==
 
==Get Stations by Bitrate or Codec Type or Genre ID==
Line 274: Line 295:
 
* Stations based on genre id
 
* Stations based on genre id
 
:<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=3&f=json&k=[Your Dev ID]</nowiki>
 
:<nowiki>http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=3&f=json&k=[Your Dev ID]</nowiki>
 +
  
 
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
 
'''<span style="color:#FF6600;">Sample JSON Response:</span>'''
Line 338: Line 360:
 
)
 
)
 
</source>
 
</source>
 +
  
 
==Get Random Stations==
 
==Get Random Stations==
Line 362: Line 385:
 
* genre - Genre 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.
 
* 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)
 
'''<span style="color:#FF6600;">Sample XML Response:</span>'''(Parameter Limit)
Line 794: Line 818:
 
==How To Tune Into A Station==
 
==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.
+
To tune into a station, find the "id" of the station from the API results & make a call to <nowiki>http://yp.shoutcast.com<base>?id=[Station_id]</nowiki> by appending the station id.
 +
 
 +
The '''<base>''' value is taken from the '''tunein''' node and based on the playlist format required (as PLS, M3U and XSPF formats are supported) you then need to choose the appropriate attribute to get the complete playlist url to use.
  
'''Ex:''' If the station id is 1025, Call => <nowiki>http://yp.shoutcast.com/sbin/tunein-station.pls?id=1025</nowiki>
+
'''Ex:''' If the station id is 1025, Call => <nowiki>http://yp.shoutcast.com/<base>?id=1025</nowiki>
  
  

Latest revision as of 14:29, 3 December 2014

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


Get Stations on SHOUTcast Radio Directory

Get Top 500 Stations

Description: Get top 500 stations on SHOUTcast Radio directory.

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

Required Parameters:

  • k - API Dev Key.

Optional Parameters:

  • limit - Limit the number of stations to return by passing the limit parameter.
Ex: http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&limit=5
  • br - Filter the stations based on bitrate specified.
Ex: http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&br=64
  • mt - Filter the stations based on media type specified.
Ex: http://api.shoutcast.com/legacy/Top500?k=[Your Dev ID]&mt=audio/aacp
MP3 = audio/mpeg and AAC+ = audio/aacp


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: http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats

Required Parameters:

  • search - Specify the query to search.
  • k - API Dev ID.

Optional Parameters:

  • limit - Limits the no of results to be returned.
Ex: http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=10
  • limit with pagination - Limits the no of results with pagination included.
Ex: http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&limit=X,Y
  • Y is the number of results to return and X is the offset.
  • br - Filter the stations based on bitrate specified.
Ex: http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&br=64
  • mt - Filter the stations based on media type specified.
Ex: http://api.shoutcast.com/legacy/stationsearch?k=[Your Dev ID]&search=ambient+beats&mt=audio/mpeg
MP3 = audio/mpeg and AAC+ = audio/aacp


Sample XML Response:

<stationlist>
 <tunein base="/sbin/tunein-station.pls"/>
 <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: http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic

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: http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&limit=X,Y
  • Y is the number of results to return and X is the offset.
  • br - Filter the stations based on bitrate specified.
Ex: http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&br=64
  • mt - Filter the stations based on media type specified.
Ex: http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&mt=audio/mpeg
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: http://api.shoutcast.com/station/nowplaying?k=[Your Dev ID]&ct=rihanna&f=xml

Required Parameters:

  • ct - Query to search in Now Playing node. This parameter also supports querying multiple artists in the same query by using "||". ex: ct=madonna||u2||beyonce up to 10 artists
  • 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.
  • br - Filter the stations based on bitrate specified.
  • mt - Filter the stations based on media type specified.
  • 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="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" cst=""/>
   <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" cst=""/>
   .
   .
  </stationlist> 
 </data>
</response>

URL (JSON Request):

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

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]","cst":"","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]","cst":"","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]","cst":"","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]","cst":"","lc":"243","ml":"70","br":"64","ct":"T.I. feat Rihanna - Live Your ife"},
     .
     .
    ]
   }
  }
 }
)


Get Stations by Bitrate or Codec Type or Genre ID

Description: Get stations which match a particular bitrate or codec type.

URL:

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

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.
  • genre_id - Genre Id from the genre API

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" cst=""/>
   <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" cst=""/>
   .
   .
  </stationlist> 
 </data>
</response>

URL (JSON Request):

  • Stations based on bitrate
http://api.shoutcast.com/station/advancedsearch?br=128&limit=3&f=json&k=[Your Dev ID]
  • Stations based on media type
http://api.shoutcast.com/station/advancedsearch?mt=mpeg&limit=3&f=json&k=[Your Dev ID]
  • Stations based on genre id
http://api.shoutcast.com/station/advancedsearch?genre_id=1&limit=3&f=json&k=[Your Dev ID]


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]","cst":"","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]","cst":"","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]","cst":"","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]","cst":"","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:

  • http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml
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.
  • http://api.shoutcast.com/station/randomstations?k=[Your Dev ID]&f=xml&mt=audio/mpeg&br=128&genre=Fresh
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):

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

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: http://api.shoutcast.com/legacy/genrelist?k=[Your Dev ID]

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: http://api.shoutcast.com/genre/primary?k=[Your Dev ID]&f=xml

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: http://api.shoutcast.com/genre/secondary?parentid=0&k=[Your Dev ID]&f=xml

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):

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

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: http://api.shoutcast.com/genre/secondary?id=25&f=xml&k=[Your Dev ID]

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):

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

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:
http://api.shoutcast.com/genre/secondary?haschildren=true&f=xml&k=[Your Dev ID]
  • Genres without sub genres:
http://api.shoutcast.com/genre/secondary?haschildren=false&f=xml&k=[Your Dev ID]

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):

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

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 http://yp.shoutcast.com<base>?id=[Station_id] by appending the station id.

The <base> value is taken from the tunein node and based on the playlist format required (as PLS, M3U and XSPF formats are supported) you then need to choose the appropriate attribute to get the complete playlist url to use.

Ex: If the station id is 1025, Call => http://yp.shoutcast.com/<base>?id=1025


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 Error Code Error Message
400 Bad Request
404 Page Not Found
440 Invalid Devid
460 Missing required parameter
462 Parameter Error
500 Generic Server Error
Business Error Code Error Message
10001 Internal Server error
10002 XML Root Element not matching
10003 Error while interacting with private api
General Error Code Error Message
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