Winamp Developer Wiki - User contributions [en]

SHOUTcast Radio Authhash API

2014-09-18T14:41:13Z

Rnsc: /* Successful Response */

==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 [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|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:
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>

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:

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>

===Error Response===
----

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

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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 [[#Status_Codes|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:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki>

'''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 [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|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'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

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

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

'''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'''

<source lang="xml">
<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>
</source>

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:''' <nowiki>http://yp.shoutcast.com/updateauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]&stationname=The Station Name&genre=Misc&[Other Parameters To Update]</nowiki>

'''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 [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|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:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''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 <nowiki>http://yp.shoutcast.com/authutil_*</nowiki> 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
<div> 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. <nowiki>http://yp.shoutcast.com/ui_checkauthhash</nowiki> 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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 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 [[SHOUTcast_Radio_Authhash_API#Supported_Genres|section 4.2]]).

==Status Codes==

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

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!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.

SHOUTcast Radio Authhash API

2014-09-18T14:38:40Z

Rnsc: /* Successful Response */

==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 [[#API_Usage|section 3]]):

:[[#Create_Authorisation_Key|Create]]
:[[#Check_Authorisation_Key|Check]]
:[[#Update_Authorisation_Key|Update]]
:[[#Remove_Authorisation_Key|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:
<syntaxhighlight lang="xml">
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
</response>
</source>
</syntaxhighlight>
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:
<syntaxhighlight lang="xml">
<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>

</data>
</response>
</source>
</syntaxhighlight>

===Error Response===
----

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

<source lang="xml">
<response>
<statusCode>440</statusCode>
<statusText>Invalid devId</statusText>

<statusDetailText>Invalid parameter k</statusDetailText>
</response>
</source>

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 [[#Status_Codes|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:''' <nowiki>http://yp.shoutcast.com/createauthhash?k=[Your Dev ID]&stationname=The Station Name&genre=Misc&[Optional Parameters To Set]</nowiki>

'''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 [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|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'''

<source lang="xml">
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<data>
<authhash>An_Authorisation_Key</authhash>
</data>
</response>
</source>

===Check Authorisation Key===
----

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

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

'''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'''

<source lang="xml">
<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>
</source>

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:''' <nowiki>http://yp.shoutcast.com/updateauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]&stationname=The Station Name&genre=Misc&[Other Parameters To Update]</nowiki>

'''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 [[#Additional_Resources|section 4.0]] for getting supported genres or [[#Supported_Genres|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:''' <nowiki>http://yp.shoutcast.com/removeauthhash?k=[Your Dev ID]&authhash=[An_Authorisation_Key]</nowiki>

'''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 <nowiki>http://yp.shoutcast.com/authutil_*</nowiki> 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
<div> 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. <nowiki>http://yp.shoutcast.com/ui_checkauthhash</nowiki> 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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!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.

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
| 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 [[SHOUTcast_Radio_Authhash_API#Supported_Genres|section 4.2]]).

==Status Codes==

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

::{| class="wikitable" border="1" cellpadding="4" cellspacing="0" style="border: 1px thin black; margin: .46em 0 0 .2em;"
|-
!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.