Grooveshark Public API version 3

View the Tutorial

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 API

Core

Search

Streams

URLS

Users (no auth)

Recs

Sessions

Trials

Autocomplete

Subscriber streams

Subscriber streams

Autoplay

Tinysong

Register

Keys

You need a web services key to access Grooveshark web services. You can request a key from us by visiting our API request form.

Signatures

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.

Access Control & Rate Limiting

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.

Request and Response Format

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.

Consuming and Contributing to User Data (Sessions and User Authentication)

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.

Errors

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 MessageError Code
Could not parse1
Invalid method2
Invalid parameter3
Missing parameter4
SSL required5
Invalid format6
Signature required7
Signature invalid8
No access rights9
Rate limit exceeded11
No sourceID12
User register failed99
User auth required100
User auth failed101
User premium required102
User mobile subscription required103
User mobile trial expired104
User trial expired105
User doesn't exist200
Song doesn't exist201
Artist doesn't exist202
Album doesn't exist203
Playlist doesn't exist204
Session required300
Location lookup failed700
Location malformed country701
Playlist duplicate name800