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
direction: the order blips are played in
possible values: top to bottom (-1) or bottom to top (1)
default: -1
autoscroll: determines whether the screen should scroll to highlight the currently playing blip
possible values: yes (1) no (0)
default: 0
repliesNotify: controls notification of new replies
possible values: 'all' - all replies, 'followers' - replies from favorite DJs, 'none'
default: 'followers'
newListenerNotify: controls notification of new listeners
possible values: yes (1) no (0)
default: 1
propsNotify: controls notification of new props
possible values: yes (1) no (0)
default: 1
reblipNotify: controls notification of new reblips
possible values: yes (1) no (0)
default: 1
help: controls whether user recommendations are shown
possible values: yes (1) no (0)
default: 1
advanced: controls whether advanced / beta features are shown
possible values: yes (1) no (0)
default: 0
volume: controls the volume of the flash player
possible values: any float between 0 and 1
default: 1
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