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 an API key (known as a wsKey) to access the Grooveshark Public API. 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 API 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.

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. Once the session is authenticated, you can pass the sessionID to methods like addUserFavoriteSong. As long as the user uses your application once every 2 weeks the sessionID can last indefinitely.

Simplified OAuth

We have adopted using a simplified OAuth for Public API integrations. Start by directing users to https://auth.grooveshark.com/ in a browser or webview with the GET params of app and callback. The app value should be equal to your API Client Name (not your secret key). The callback should be a URL that the user can be redirected to upon successful authentication or the user cancelling authentication. The user will log in to their Grooveshark account on the auth.grooveshark.com site and then redirected to callback. One of two possible GET params will be included depending on whether authentication was successful: token when a token is generated successfully and cancel when the user cancels. Pass the token value to authenticateToken to log the user into the session. The token can be stored indefinitely, alongside the sessionID, and used to authenticate a new sessionID whenever a sessionID expires.

Integrated Approach

An alternative approach to authenticating can be done via authenticateEx by providing sessionID, the user's lowercased username (an email is also valid) and the user's password over HTTPS. Assuming the user has provided their correct username and password to you, you will then have an authenticated session. The sessionID should be stored and NOT the user credentials. Contact us if you need access to the integrated authentication and cannot use the simplified OAuth approach.

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