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. If you're interested in streaming, please see the Streaming API tutorial.
Request Access to APIYou need a web services key to access Grooveshark web services. You can request a key from us by visiting our API request form.
Signatures are created using HMAC (using MD5 as its hash function). To generate a hash for use as the signature, you simply need to use a provided secret to encrypt the entire request string. When the API receives the request, it performs the same hash 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 variable.
An example of this hashing can be seen in the provided PHP implementation on the downloads page.
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 limit to the number of requests that can be fulfilled in a given timeframe. Please contact us at developers@grooveshark.com if you are not able to access a method or need to have your key's rate limiting modified.
The API works by accepting a raw 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 variable.
Example (using the word secret as the secret):
http://api.grooveshark.com/ws3.php?sig=cd3ccc949251e0ece014d620bbf306e7
{'method': 'addUserFavoriteSong', 'parameters': {'songID': 0}, 'header': {'wsKey': 'key', 'sessionID': 'sessionID'}}
The API returns its data as JSON-encoded objects. The API is similar to JSON-RPC but not quite.
To modify and access user data an authenticated session is required. To create a session, invoke startSession with your web services key and signature. You will be returned an anonymous, unauthenticated session. To then authenticate this session, invoke authenticateUser providing sessionID, the user's lower-cased username and a token for that user. The token is formed as md5(lowercase(username) + md5(password)). 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. However, error states can be discerned from the result property of the result object. For example, the method to create playlists will always return a playlistID property, regardless of whether or not the method succeeded. In cases of success, playlistID will be a positive integer. In cases of failure, playlistID will be 0 (zero). Other methods, ones that simply perform actions, usually return a success boolean.
| Error Message | Error Code |
|---|---|
| Could not parse | 1 |
| Invalid method | 2 |
| Invalid parameter | 3 |
| Missing parameter | 4 |
| SSL required | 5 |
| Invalid format | 6 |
| Signature required | 7 |
| Signature invalid | 8 |
| No access rights | 9 |
| Rate limit exceeded | 11 |
| No sourceID | 12 |
| 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 |
| Session required | 300 |
| Location lookup failed | 700 |
| Location malformed country | 701 |
| Playlist duplicate name | 800 |
