SHOUTcast Radio Authhash API

From Winamp Developer Wiki
Jump to: navigation, search

SHOUTcast Home | SHOUTcast Server (DNAS) | SHOUTcast Developer (API) | Streaming Service & Revenue Generation | SHOUTcast DSP (encoder Plug-In for Winamp)


Introduction

A key aspect of the SHOUTcast 2.0 system is the usage of authorisation keys to control the listing of stations within the SHOUTcast Radio Directory (otherwise known as the YP).

The API which is documented here is provided as a means for registered developers to be able to obtain and manage any authorisation keys for the station(s) they are providing.


API Overview

There are four core parts of the authorisation key APIs (usage details are in section 3):

Create
Check
Update
Remove

The authorisation key APIs are xml based responses which provide information and status details of the provided API methods in a common style to ease implementation and usage.

The API methods are called by passing parameters to the required YP site url.

When the API methods are called then the status code of the method response is set to the status code of the API method so it is easy to detect errors from calling the API method.


Successful Response


If there are no issues with the API method call then one of the following responses will be received as the response generated.


The first response is the basic success response and is provided if there is no extra information to be returned by the API method:

<response>
 <statusCode>200</statusCode>
 <statusText>Ok</statusText>
</response>

The second response is the full success response and is provided when the API method needs to return additional information such as the authorisation key when a new one is created or the details of the authorisation key when using the 'check' method:

<response>
 <statusCode>200</statusCode>
 <statusText>Ok</statusText>
 <data>
  <!-- information is found here -->
 </data>
</response>

Error Response


If there are issues experienced during the API method call then an error response will be received which takes the following form:

<response>
 <statusCode>440</statusCode>
 <statusText>Invalid devId</statusText>
 <!-- the following is optional dependent upon the error -->
 <statusDetailText>Invalid parameter k</statusDetailText>
</response>

In all uses of the API methods, the 'statusCode' and 'statusText' elements are provided when an error occurs. The 'statusDetailText' value is an optional element and is only provided if the internal error handling is able to provide additional information. This will usually be present for errors relating to parameter issues i.e. missing parameters.

See section 5 for the status codes and messages returned when using the API methods.


API Usage

The following sections detail how to use the four authorisation key API methods.

Importantly, once an authorisation key has been created then it will be locked to the Developer ID used so you can only check, update or remove authorisation keys against that Developer ID.


Create Authorisation Key


This will create an authorisation key and will return it in the xml response on success.

Any parameters which are not specified and do not cause an error will be left at their default values which will be indicated by empty xml elements when using the 'check' API.

URL: http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]

Required Parameters:

  • k - Developer ID for accessing the API
  • stationname - name of the station as listed in the YP listings up to 100 characters
  • genre - genre describing the station (see section 4.0 for getting supported genres or section 4.2 for list of supported genre values)
  • email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)

Recommended Optional Parameters: (These are marked as optional but are likely to be made required in a future update)

  • langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
  • countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

Optional Parameters:

  • website - related url for station up to 128 characters
  • description - brief description about the station up to 65535 characters
  • stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
  • city - more specific place where the stream is based or related up to 128 characters
  • keywords - separated tag words about the stream up to 120 characters
  • private - determine if the primary server should be public (0 - default) or not (1)
It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

Response:

Returns a full success response containing the new authorisation key or the standard error response.

Example Response

<response>
 <statusCode>200</statusCode>
 <statusText>Ok</statusText>
 <data>
  <authhash>An_Authorisation_Key</authhash>
 </data>
</response>


Check Authorisation Key


This will remove an authorisation key as long as it was created by the Developer ID used.

URL: http://yp.shoutcast.com/checkauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]

Required Parameters:

  • k - Developer ID for accessing the API
  • authhash - Authorisation Key to check

Response:

Returns a full success response containing the found details of the authorisation key or the standard error response.

Example Response

 <response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <data>
   <stationname>The Station Name</stationname>
   <genre>Misc</genre>
   <website>www.shoutcast.com</website>
   <description>The Best Station Ever...!</description>
   <langid>EN</langid>
   <countryiso>US</countryiso>
   <stateiso>00</stateiso>
   <city></city>
   <keywords>Greatest Web Station</keywords>
   <private>0</private>
  </data>
 </response>
The <stateiso> element will only be returned if the <countryiso> element is 'US'.


Update Authorisation Key


This will update an authorisation key as long as it was created by the Developer ID used.

Any parameters which are not specified and do not cause an error when making an update are reset to their default value when this completes. Otherwise this acts the same as the 'create' API with the addition of specifying the authorisation key to update.

URL: http://yp.shoutcast.com/updateauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]&stationname=The Station Name&genre=Misc&[Other Parameters To Update]

Required Parameters:

  • k - Developer ID for accessing the API
  • authhash - Authorisation Key to update
  • stationname - name of the station as listed in the YP listings up to 100 characters
  • genre - genre describing the station (see section 4.0 for getting supported genres or section 4.2 for list of supported genre values)
  • email - contact address for the station up to 255 characters (this is so we can contact you easily in-case of an issue with your listing or needing to inform you of a required DNAS update)

Recommended Optional Parameters: (These are marked as optional but are likely to be made required in a future update)

  • langid - ISO 639-1 code of the language the station mainly broadcasts e.g. English would be EN (defaults to EN)
  • countryiso - ISO 3166-1-alpha-2 code of the country the station is run e.g. United Kingdom would be GB (defaults to US)

Optional Parameters:

  • website - related url for station up to 128 characters
  • description - brief description about the station up to 65535 characters
  • stateiso - USPO state code (only used if countryiso = US) and defaults to 00 (general)
  • city - more specific place where the stream is based or related up to 128 characters
  • keywords - separated tag words about the stream up to 120 characters
  • private - determine if the primary server should be public (0 - default) or not (1)
It is recommended to fill in as many of these optional details where possible
to improve usability with any future YP features which may be introduced.

Response:

Returns a basic success response or the standard error response.


Remove Authorisation Key


This will remove an authorisation key as long as it was created by the Developer ID used.

URL: http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]

Required Parameters:

  • k - Developer ID for accessing the API
  • authhash - Authorisation Key to remove

Response:

Returns a basic success response or the standard error response.


Additional Resources

In addition to the core API methods, some additional methods are provided for accessing the supported primary and secondary genres, country, state and language codes. These are provided as a means to check you are using the correct values or to use if creating your own interface around the core authorisation key APIs.


These additional methods are accessed via http://yp.shoutcast.com/authutil_* where * is then replaced with one of the following to get the required information:

  • country - provides provides a html select control containing the ISO 3166-1-alpha-2 code and a displayable string for each option in the control
  • languages - provides provides a html select control containing the ISO 639-1 code and a displayable string for each option in the control
  • states - provides provides a html select control containing the USPO state code and a displayable string for each option in the control
  • primarygenre - provides a html select control of the primary genre's recognised
  • secondarygenre?primarygenre=<genre> - provides a html select control of the secondary genre's related to the primary genre passed or an empty response if there is no genres found
  • parentgenre?genre=<genre> - provides the name of the parent genre of the passed genre or an empty response if there is no parent genre


All additional methods (excluding the 'parentgenre' method) provide a fully formed html select control which is filled with relevent values based on the parameter passed to the method (if applicable). These are done like this to allow for ease of insertion into a

element for example with an interface used to control the APIs.

Calling these additional methods (excluding the 'parentgenre' method) with '&raw=1' in the url will output the result (if applicable) as plain text instead of as a html select control. The values returned are separated by a comma and each data pair is then placed on a new line. This is provided as a quick way of getting the recognised values if the html select control is not suitable.


User Interface Versions


In addition to the core API methods, specifying 'ui_' on the front of the API method e.g. http://yp.shoutcast.com/ui_checkauthhash for the 'check' method provides a pre-built interface pages which can be used as a base point for making your own interface for the authorisation key APIs or to use as is as long as you have the required developer access.


Supported Genres


The genre specified for an authhash can only be a primary genre (e.g. Misc) or it can be a secondary genre related to a chosen primary genre (e.g. House from Electronic). The following lists the supported primary genres and the associated secondary genres to them.

Primary Genre Associated Secondary Genres
Alternative Adult Alternative, Britpop, Classic Alternative, College, Dancepunk, Dream Pop, Emo, Goth, Grunge, Hardcore, Indie Pop, Indie Rock, Industrial, LoFi, Modern Rock, New Wave, Noise Pop, Post Punk, Power Pop, Punk, Ska, Xtreme
Blues Acoustic Blues, Cajun and Zydeco, Chicago Blues, Contemporary Blues, Country Blues, Delta Blues, Electric Blues
Classical Baroque, Chamber, Choral, Classical Period, Early Classical, Impressionist, Modern, Opera, Piano, Romantic, Symphony
Country Alt Country, Americana, Bluegrass, Classic Country, Contemporary Bluegrass, Contemporary Country, Honky Tonk, Hot Country Hits, Western
Decades 30s, 40s, 50s, 60s, 70s, 80s, 90s, 00s
Easy Listening Exotica, Light Rock, Lounge, Orchestral Pop, Polka, Space Age Pop
Electronic Acid House, Ambient, Big Beat, Breakbeat, Dance, Demo, Disco, Downtempo, Drum and Bass, Dubstep, Electro, Garage, Hard House, House, IDM, Jungle, Progressive, Techno, Trance, Tribal, Trip Hop
Folk Alternative Folk, Contemporary Folk, Folk Rock, New Acoustic, Old Time, Traditional Folk, World Folk
Inspirational Christian, Christian Metal, Christian Rap, Christian Rock, Classic Christian, Contemporary Gospel, Gospel, Praise and Worship, Sermons and Services, Southern Gospel, Traditional Gospel
International African, Afrikaans, Arabic, Asian, Bollywood, Brazilian, Caribbean, Celtic, Chinese, Creole, European, Filipino, French, German, Greek, Hawaiian and Pacific, Hebrew, Hindi, Indian, Islamic, Japanese, Klezmer, Korean, Mediterranean, Middle Eastern, North American, Russian, Soca, South American, Tamil, Turkish, Worldbeat, Zouk
Jazz Acid Jazz, Avant Garde, Big Band, Bop, Classic Jazz, Cool Jazz, Fusion, Hard Bop, Latin Jazz, Smooth Jazz, Swing, Vocal Jazz, World Fusion
Latin Bachata, Banda, Bossa Nova, Cumbia, Flamenco, Latin Dance, Latin Pop, Latin Rap and Hip Hop, Latin Rock, Mariachi, Merengue, Ranchera, Reggaeton, Regional Mexican, Salsa, Samba, Tango, Tejano, Tropicalia
Metal Black Metal, Classic Metal, Death Metal, Extreme Metal, Grindcore, Hair Metal, Heavy Metal, Metalcore, Power Metal, Progressive Metal, Rap Metal, Thrash Metal
Misc
New Age Environmental, Ethnic Fusion, Healing, Meditation, Spiritual
Pop Adult Contemporary, Barbershop, Bubblegum Pop, Dance Pop, Idols, JPOP, KPOP, Oldies, Soft Rock, Teen Pop, Top 40, World Pop
Public Radio College, News, Sports, Talk, Weather
R&B and Urban
Rap Alternative Rap, Dirty South, East Coast Rap, Freestyle, Gangsta Rap, Hip Hop, Mixtapes, Old School, Turntablism, Underground Hip Hop, West Coast Rap
Reggae Contemporary Reggae, Dancehall, Dub, Pop Reggae, Ragga, Reggae Roots, Rock Steady
Rock Adult Album Alternative, British Invasion, Celtic Rock, Classic Rock, Garage Rock, Glam, Hard Rock, Jam Bands, JROCK, Piano Rock, Prog Rock, Psychedelic, Rock & Roll, Rockabilly, Singer and Songwriter, Surf
Seasonal and Holiday Anniversary, Birthday, Christmas, Halloween, Hanukkah, Honeymoon, Kwanzaa, Valentine, Wedding, Winter
Soundtracks Anime, Kids, Original Score, Showtunes, Video Game Music
Talk BlogTalk, Comedy, Community, Educational, Government, News, Old Time Radio, Other Talk, Political, Scanner, Spoken Word, Sports, Technology
Themes Adult, Best Of, Chill, Eclectic, Experimental, Female, Heartache, Instrumental, LGBT, Love and Romance, Party Mix, Patriotic, Rainy Day Mix, Reality, Se xy (remove space for actual word - spam filter display issue), Shuffle, Travel Mix, Tribute, Trippy, Work Mix

Illegal Input Values


The following values are not allowed when entered as the stationname (case insensitively) and will cause a 456 error response to be received when an authorisation key is created or updated as they are not easily found when multiple other listings are also using the same stationame.

127.0.0.1 admin auto dj auto jedi
auto pj auto-dj autodj autopj
demo dj internet radio live
local server localhost localserver music
my radio my server my station name my test server
n/a pj playlist radio
radio station test test server unnamed server
virtual dj virtualdj web rdio web radio
song teste default stream radio stream

Additionally, stationnames just containing punctuation are not allowed as well as any which specify a name which matches with the supported genres (see section 4.2).


Status Codes

The following status codes are returned on success or error when using the provided APIs:

Code Status Text Detailed Text (if available)
200 Ok n/a
400 Generic Error n/a
404 Page Not Found n/a
440 Invalid devId Invalid parameter k
456 Parameter value not allowed <variable>=<value> not allowed
458 Building internal value failure n/a
459 Authhash could not be found for reading Authhash does not exist or was not created by this 'devID'
460 Missing required parameter Missing <variable>
461 Error while updating authhash n/a
462 Parameter error Invalid parameter <variable>
463 Invalid station result returned n/a
464 Authhash could not be found or removed Authhash does not exist or was not created by this 'devID'
465 Required parameter missing for registration <variable> is a required parameter
466 Parameter outside of allowed range <variable> parameter too long
467 Parameter value not recognized in stored values <variable> value not recognized
468 Error creating intended xml response n/a
469 Authhash could not be updated as not found Authhash does not exist or was not created by this 'devID'
470 Invalid authorization hash n/a
500 Generic Server Error n/a
Note: The <variable> value in the detailed text will be replaced with the parameter name which the error relates to. The <value> value in the detailed text will be replaced with the parameter value which the error relates to.