Introduction

Hello & welcome to the Blip.fm API. This document may contain probably contains typos... enjoy.

Currently in Private Beta

These API documents (and the Blip.fm API) are a work in progress and will be changing without notice over the period of the beta. Feel free to experiment with the public endpoints but be advised that any application you build with them might break unexpectedly. We're currently holding off on giving out any more api keys, however you can email us at api@blip.fm to be added to our waitlist. Thanks for your interest!

Getting Help

Currently the best way to get real-time support is by joining us in the IRC channel #blipfm on irc.freenode.net. You can also email us at api@blip.fm

API Test Tool

An API Test Tool is available at http://api.blip.fm/apiTools. This web based tool has all the necessary form fields needed to test and view the output of all API calls.

Each method description below has a direct link to test that particular API call.

API Libraries

We have taken some of the leg work out of developing your applications by providing several API client libraries (well, three so far). Pick your poison:
CAUTION: These libraries are out of date and should only be used to snag some useful functions or get some ideas.

Examples:

Parameters

All the API endpoints are documented below. The documentation includes information about each parameter including the parameter's expected data type, if its a required field & whether or not the API accepts the parameter as an array.

If a parameter accepts an array as a value then you can optionally send the value as a comma separated list. Here's an example:

Single blip by id: /blip/getById?id=1
Multiple blips by an "array" of id's: /blip/getById?id=1,2,3

API Authentication

Most requests sent to the Blip.fm API must include all the parameters in the following table.

Parameter name Sample value Description
apiKey 1ea6fd96887c63abdaa6 Your API key. Specifies the secret key used to sign the request and the identity of the requestor.
nonce 3x8GAjXNW A random string of at least 7 characters. Uniquely identifies the request.
timestamp 1175139620 The UNIX timestamp (UTC time in seconds since epoch) used to sign the request.
signature 2cQrvc%2BvKpVnzcI8s%2FVmS2iwn1Q%3D The URL encoding of the Base64 encoding of the HMAC-SHA1 of StringToSign.
(see 'Signing Your Requests' below on how to generate this signature)

Examples of properly formed URLs:

http://api.blip.fm/blip/getById.xml?id=1

http://api.blip.fm/blip/getUserPlaylist.xml?username=fuzzygroove&apiKey=12wh1e54j1f$5f&nonce=thx1138.38×tamp=1222804538&signature=58jg45d!h@2d4fg5ds9g%d12sdfad14f

http://demo:demouser@api.blip.fm/blip/getUserHome.xml?apiKey=12wh1e54j1f$5f&nonce=thx1138.39×tamp=1222805227&signature=58jg45d!h@2d4fg5ds9g%d12sdfad14f

Signing Your Requests

The following is pseduocode for building the signature to be included with your request.

StringToSign = HTTP_REQUEST_METHOD + "\n" + timestamp + "\n" + nonce; // HTTP_REQUEST_METHOD is "GET" or "POST"
Signature = URLEncode( Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) ) );

Once you've generated your signature, you attach it to the query string (or add it as a POST parameter if posting). The following is an example of building a signature in PHP using PEAR's Crypt HMAC package:

<?
    require_once ('PEAR/Crypt/HMAC.php');

    function hex2b64 ($str) 
    {
        $raw = '';
        for ($i=0; $i < strlen($str); $i+=2) 
        {
            $raw .= chr(hexdec(substr($str, $i, 2)));
        }
        
        return base64_encode($raw);
    }

    $reqMethod = 'GET';
    $timestamp = 1175139620;
    $nonce = '3x8GAjXNW';
    $secretKey = 'brREsLcDUIKVtr%a3AqOWuB3qB0eEL&3rsHj%';
     
    $strToSign = $reqMethod . "\n" . $timestamp . "\n" . $nonce;
    $hasher =& new Crypt_HMAC ($secretKey, "sha1");
    $signature = urlencode (hex2b64($hasher->hash($strToSign)));
?>

HTTP Basic Authentication

Basic Authentication has been deprecated. Please use Digest Authentication as described below.

HTTP Digest Authentication

Some methods may require HTTP Digest Authentication. Almost all methods that require authentication perform an operation on behalf of the authenticated user or retreive/alter account information for the authenticated user.

When calling a method that requires Digest Authentication, use the 'username' (or 'urlName') and 'appKey' of the Blip.fm user account you wish to access. The appKey is not provided in the API results, it must be provided by the user and should be kept secure if stored.

Take a look each method's details to determine whether or not it requires authentication.

Here's an example of Digest Authentication in PHP with curl:

<?
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($ch, CURLOPT_TIMEOUT, 20);
    curl_setopt($ch, CURLOPT_URL, $apiUrl);

    // HTTP Digest Authentication
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
    curl_setopt($ch, CURLOPT_USERPWD, '<BLIPFM_USERNAME>:<BLIPFM_APPKEY>');

    curl_setopt($ch, CURLOPT_USERAGENT, 'My PHP Script');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $result = curl_exec($ch);
    curl_close($ch);
?>

Output

The default output format for all API calls is XML but you can optionally tell the API to return JSON or serialized PHP.

In order to change the output you just tack on .json, .php or .xml to the end of the URI. Since XML is the default format you really don't have to bother with the .xml part.

Here's an example of hitting the /util/hello endpoint & retrieving the data in all possible formats:

Rate Limits

Each API key is limited to 120 HTTP authenticated requests per user per hour. The following endpoints are excluded from this limit.

  • /blip/post
  • /blip/delete
  • /favorite/addDJ
  • /favorite/removeDJ
Non-authenticated requests are not currently under any rate limitations. Please contact api@blip.fm if you would like to request a higher rate limit / whitelisting.

Available Services

Here's a list of the services exposed by the Blip.fm API.

BlipService top

/blip/delete

Description: Delete a blip. The authorized user must be the owner of the blip.

URL: http://api.blip.fm/blip/delete (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: True on success. Error message on failure.

Name Description Required? Type Default
id The id of the blip to be deleted yes int -
/blip/getById

Description: Use this to get a Blip by id.

URL: http://api.blip.fm/blip/getById (xml | json | php)
Method: GET
Requires API Key?: no
Requires Authentication?: no
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
id The id(s) of the blip(s) you want to fetch. yes int | array -
/blip/getProfileWidgetData

Description: Get data used to build the profile widget: http://blip.fm/widgets

URL: http://api.blip.fm/blip/getProfileWidgetData (xml | json | php)
Method: GET
Requires API Key?: no
Requires Authentication?: no
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose Blips you wanna get. yes string -
offset The offset you wanna get stuff at. no int 0
limit How many Blips do you wanna get? no int 25
/blip/getPublic

Description: Get public blips (the all blips page) that posted after the timestamp parameter, ordered by recency.

URL: http://api.blip.fm/blip/getPublic (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
ts Unix timestamp (in seconds). Blips posted after this timestamp will be returned. Default is 2 days ago. no int 0
offset The offset you wanna get blips at. no int 0
limit How many blips do you wanna get? no int 25
/blip/getUserHome

Description: Get a user's personal station blips (blips from people they are following).

URL: http://api.blip.fm/blip/getUserHome (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: yes
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
ts Unix timestamp (in seconds). Blips posted after this timestamp will be returned. no int -
offset The offset you wanna get stuff at. no int 0
limit How many Blips do you wanna get? no int 25
/blip/getUserPlaylist

Description: Get a user's playlist blips.

URL: http://api.blip.fm/blip/getUserPlaylist (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose playlist you want to get. yes string -
/blip/getUserProfile

Description: Get Blips for a User ordered by recency.

URL: http://api.blip.fm/blip/getUserProfile (xml | json | php)
Method: GET
Requires API Key?: no
Requires Authentication?: optional
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose Blips you wanna get. yes string -
offset The offset you wanna get stuff at. no int 0
limit How many Blips do you wanna get? no int 25
/blip/getUserReplies

Description: Get blips that have replies to a user.

URL: http://api.blip.fm/blip/getUserReplies (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of blips on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose replies you want to get. yes string -
offset The offset you wanna get blips at. no int 0
limit How many blips do you wanna get? no int 150
/blip/ping

Description: DEPRECATED Use the ts parameter of the /blip/getPublic and /blip/getUserHome endpionts instead.
Get blips posted after a given time.

URL: http://api.blip.fm/blip/ping (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Current timestamp and a collection of blips on success. Error message on failure.

Name Description Required? Type Default
ts Unix timestamp (in seconds). Blips posted after this timestamp will be returned. yes int -
station The station ('home', 'all', 'artist', 'genre', or 'tag') you want to ping. Authentication is required if this is set to 'home'. yes string home
tag If you request station type 'artist', 'genre', or 'tag' you must also send a string representing that tag no string -
offset The offset you wanna get stuff at. no int 0
limit How many Blips do you wanna get? no int 25
/blip/post

Description: Post a blip.

URL: http://api.blip.fm/blip/post (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Blip that was just posted and users to recommend on success. Error message on failure.

Name Description Required? Type Default
artist The artist of the song to be blipped. no string -
title The title of the song to be blipped. yes string -
url The url or unique identifier of the song to be blipped. yes string -
message The message attached to the song to be blipped. no string -
bitrate The bitrate of the song (e.g. 128000, 192000, or 320000). no string -
genre The genre of the song (e.g. 'punk', 'rock', 'christian death metal'). no string -
blipType The type of the blip. yes string songUrl
reblipId If this blip to be a posted is a reblip, pass the id of the original blip in this field no int 0
getUserRecs Get user recommendations based off the posted blip. accepts 'true' or 'false' no boolean 1

FavoriteService top

/favorite/addDJ

Description: Add a user as a favorite DJ.

URL: http://api.blip.fm/favorite/addDJ (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Favorited User on success. Error message on failure.

Name Description Required? Type Default
username The username of the DJ to add as a favorite. yes string -
/favorite/addToPlaylist

Description: Add a blip to a user's playlist.

URL: http://api.blip.fm/favorite/addToPlaylist (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Blip that was added to playlist on success. Error message on failure.

Name Description Required? Type Default
blipId The id of the blip to add to the playlist. yes int -
/favorite/removeDJ

Description: Remove a user as a favorite DJ.

URL: http://api.blip.fm/favorite/removeDJ (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Removed user on success. Error message on failure.

Name Description Required? Type Default
username The username of the DJ to remove as a favorite. yes string -
/favorite/removeFromPlaylist

Description: Remove a user as a favorite DJ.

URL: http://api.blip.fm/favorite/removeFromPlaylist (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Removed blip on success. Error message on failure.

Name Description Required? Type Default
blipId The id of the blip to remove from the playlist. yes int -
/favorite/updatePlaylist

Description: Update the order of user's playlist.

URL: http://api.blip.fm/favorite/updatePlaylist (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: Collection of blips, the updated playlist, on success. Error message on failure.

Name Description Required? Type Default
ids Comma separated list of the updated order of playlist blip ids. Note: You should always send back the full list of blip ids, otherwise the reorder may not occur as expected. yes int | array -

SearchService top

/search/findSongs

Description: Find songs by song name or artist.

URL: http://api.blip.fm/search/findSongs (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: no
Returns: Collection of songs on success. Error message on failure.

Name Description Required? Type Default
searchTerm The song or artist to search for. yes string -
/search/findUsers

Description: Find users by username or artist. The result set contains a collection of users that have the searchTerm in their username ('byName'), and users who have blipped songs by an artist matching the searchTerm ('byArtist').

URL: http://api.blip.fm/search/findUsers (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: no
Returns: Collection of users on success. Error message on failure.

Name Description Required? Type Default
searchTerm The username or artist to search for. yes string -
offset The amount by which the initial result of the set is out of line. no int 0
limit How many users do you want? no int 25

UserService top

/user/getByUsername

Description: Use this to get a User by username. If password is provided, the user will be returned with attached preferences. Note: urlName and username are effectively synonymous.

URL: http://api.blip.fm/user/getByUsername (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of users on success. Error message on failure.

Name Description Required? Type Default
username The username of the User(s) you want to fetch yes string | array -
password The (optional) password of the user to fetch in order to receive the returned user with attached preferences. no string -
/user/getFavoriteDJs

Description: Get the User's favorite DJs.

URL: http://api.blip.fm/user/getFavoriteDJs (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of users on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose favorite DJs you want to get. yes string -
offset The offset you want to get users at. no int 0
limit How many favorite DJs do you wannt to get (default 25)? no int 25
/user/getListeners

Description: Get the User's listeners.

URL: http://api.blip.fm/user/getListeners (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: optional
Returns: Collection of users on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose listeners you want to get. yes string -
offset The offset you wanna get stuff at. no int 0
limit How many listeners do you want to get (default 25)? no int 25
/user/getPreferences

Description: Get a user's preferences

URL: http://api.blip.fm/user/getPreferences (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: yes
Returns: The user's preferences on success. Error message on failure.

Name Description Required? Type Default
No parameters
/user/getStats

Description: Get a user's stats - # blips in playlist, # previous blips, # replies received, # props received, # favorite djs, # listeners.

URL: http://api.blip.fm/user/getStats (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: no
Returns: Stats object on success. Error message on failure.

Name Description Required? Type Default
username The username of the User whose stats you want to get. yes string -
/user/giveProps

Description: Give a user props (either for a blip or directly).

URL: http://api.blip.fm/user/giveProps (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: yes
Returns: User's remaining number of props. Error message on failure.

Name Description Required? Type Default
username The user to whom you are giving props. yes string -
blipId The id of the blip to give props to. If not included, props will go directly to the user no int -
/user/savePreferences

Description: Save a user's preferences. NOTE: Any unset preferences will retain their current values. The preference options are detailed below:

Click to see preference options details

URL: http://api.blip.fm/user/savePreferences (xml | json | php)
Method: GET
Requires API Key?: yes
Requires Authentication?: yes
Returns: The user's updated preferences on success. Error message on failure.

Name Description Required? Type Default
preferences JSON representation of the user's preferences to be saved
example:
{"direction":-1, "autoscroll":0, "repliesNotify":"followers", "newListenerNotify":1, "propsNotify":1, "reblipNotify":1, "help":1, "advanced":0, "volume":"0.5"}		 yes string -
/user/signup

Description: Sign up a new user.

URL: http://api.blip.fm/user/signup (xml | json | php)
Method: POST
Requires API Key?: yes
Requires Authentication?: no
Returns: New user on success. Error message on failure.

Name Description Required? Type Default
username The DJ name of the new user. yes string -
emailAddress The email address of the new user. yes string -
password The password of the new user. yes string -

UtilService top

/util/hello

Description: Check if the server's responding.

URL: http://api.blip.fm/util/hello (xml | json | php)
Method: GET
Requires API Key?: no
Requires Authentication?: no
Returns: string

Name Description Required? Type Default
No parameters
/util/time

Description: Get the server's current unixtime

URL: http://api.blip.fm/util/time (xml | json | php)
Method: GET
Requires API Key?: no
Requires Authentication?: no
Returns: int

Name Description Required? Type Default
No parameters