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...)
 
(add navbar template)
Line 1: Line 1:
 +
{{Template:NavBar}}
 +
 
=Get Stations on SHOUTcast Radio Directory=
 
=Get Stations on SHOUTcast Radio Directory=
  

Revision as of 03:32, 15 January 2011

Wiki Main | Skin Developer | Visual Developer | Plug-in Developer | Online Service Developer | SHOUTcast Tools & Services | Articles Page | FAQ | Glossary

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

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.
  • Filter by Codec type - Get stations which match the codec type requested.
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"></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: 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.
  • Filter by Codec type - Get stations which match the codec type requested.
Ex: http://api.shoutcast.com/legacy/genresearch?k=[Your Dev ID]&genre=classic&&mt=audio/aacp
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.
  • 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>
 
  <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> 
 
</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]","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
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 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.

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>
 
  <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> 
 
</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]

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:

  • 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>
 
  <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>
 
</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>
 
  <genrelist> 
   <genre name="Alternative" id="1" parentid="0" haschildren="true"/>
   <genre name="Blues" id="24" parentid="0" haschildren="true"/>
   .
   .
   .
  </genrelist> 
 
</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>
 
  <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>
 
<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>
 
  <genrelist> 
   <genre name="Acoustic Blues" id="25" parentid="24" haschildren="false"/>
  </genrelist> 
 
</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>
 
  <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> 
 
</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/sbin/tunein-station.pls?id=[Station_id] by appending the station id.

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


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