Grooveshark makes available methods for accessing and interacting with Grooveshark data. All methods require a web services key and you must sign your requests with a secret we provide.
|Error Message||Error Code|
|Could not parse||1|
|No access rights||9|
|Rate limit exceeded||11|
|User register failed||99|
|User auth required||100|
|User auth failed||101|
|User premium required||102|
|User mobile subscription required||103|
|User mobile trial expired||104|
|User trial expired||105|
|User doesn't exist||200|
|Song doesn't exist||201|
|Artist doesn't exist||202|
|Album doesn't exist||203|
|Playlist doesn't exist||204|
|Location lookup failed||700|
|Location malformed country||701|
|Playlist duplicate name||800|
You need a web services key to access Grooveshark web services and you can request a key by visiting our API request form.
A signature is required for each of your requests in order to verify the authenticity of the call. Signatures are created using HMAC (using MD5 as its hash function). To generate the hash, you simply need to use a provided secret to encrypt the entire JSON payload. When the API receives the request, it performs the same procedure and compares its hash to the hash you"ve provided. If the hashes match, the request is fulfilled. You should send this signature using the sig GET parameter.
Each web services key is assigned a set of permissions, which means that not all keys can access all methods. Furthermore, each key has a limited number of requests that can be fulfilled in a given timeframe. Please contact us at firstname.lastname@example.org if you are not able to access a method or need to have your key's rate limiting increased.
The API works by accepting a POST JSON payload that contains the method as a key, the parameters as a key, along with the sessionID and wsKey as a key inside header. The signature must be sent via the query string as the sig parameter.
All requests are sent to the following endpoint: http://api.grooveshark.com/ws3.php
To modify and access user data an authenticated session is required. To create a session, send a request to startSession. You will be returned an anonymous, unauthenticated session that expires after 2 weeks if unused. We encourage you to recycle sessionIDs if you are not authenticating a user. If you are authenticating a user, it is recommended to store the sessionID in your database instead of the user's username and password as the password could change and is potentially less risky for the user.
To authenticate this session, invoke authenticate providing sessionID, the user's username (lowercased) and the user's password. The user's password should be sent encrypted using md5 and the request should be made through HTTPS. Assuming the user has provided their correct username and password to you, you will then have an authenticated session. You can then pass this sessionID to methods like addUserFavoriteSong.
The API can return error objects in its response. The error objects are contained within a JSON array named errors. The API error codes are standard, meaning that, for example, the error code for "session required" in one method will be the same error code used in another method. API errors are experimental and their structure, codes, and messages may change.