Public API

Overview

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

Keys and Signatures

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.

Access Control and 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 limited 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 increased.

Request and Response Format

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

Example (Key: key, Secret: secret):

POST URL
http://api.grooveshark.com/ws3.php?sig=f699614eba23b4b528cb830305a9fc77

POST payload
{"method":'addUserFavoriteSong",'parameters":{"songID":30547543},"header":{"wsKey":'key","sessionID":'df8fec35811a6b240808563d9f72fa2'}}

Sessions and User Authentication

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.

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.