MP3tunes Music API

Overview
New Features in Music API v1
Authentication
1. login
2. accountData
Accessing User Lockers and Playing Tracks
Music Sync

Overview ↩

The MP3tunes Music API consists mainly of an easy to use REST interface which gives you access to all data for a user within the MP3tunes Locker service.

Music API Version ↩

Current Version

MP3tunes Music API v1 (this document)
- September, 2007 - Initial release of v1
- October, 2007 - JSON callback function added, playlist data fixes and clarification
- February, 2008 - lastUpdate call added, ability to fetch PlayMix data separately from user created playlists added

Previous Versions

MP3tunes Music API v0 - March, 2006

Technical Resources ↩

MP3tunes Developer Forum - this is the best place to post questions and comments
MP3tunes Developer Wiki - contains additional development resources

API Domains and URLs ↩

The MP3tunes service has a set of servers dedicated to specific tasks, and it is important that when using the API you use the correct servers for specific types of requests. These servers are separated by mp3tunes.com subdomains. Each request method’s documentation will list the correct subdomain to use for that method. Currently there are three subdomains, and respectively three types of requests.

Authentication API methods: API methods which deal with authentication (SSL) should use the https://shop.mp3tunes.com/ – mainly for login calls.
General API methods: http://ws.mp3tunes.com/
Storage API methods: http://content.mp3tunes.com/

Request and Response Formats ↩

Requests format ↩

All calls to the MP3tunes v1 API are accessed with the v1 URL. Example: http://ws.mp3tunes.com/api/v1/….

All requests to the MP3tunes API are via REST requests (REpresentational State Transfer):

http://ws.mp3tunes.com/api/v1/<method>?<params>

All requests require a partner token (as parameter “partner_token”). If you don’t yet have a partner token, one can be created easily and used immediately. See our partner page for details.

All requests for data require a session ID (as parameter “sid”). A session ID can be obtained using the login call.

Response format ↩

Currently JSON and XML response formats are supported. You may choose the response format by passing the “output” parameter with a value of either “xml” or “json”. If no output parameter is passed the response defaults to JSON.

It is easiest to debug and view the output of API calls using XML output, even if you end up using JSON output in your application, for the simple reason that XML is easier to parse with your eyes.

Album data excerpt using JSON output:

{"artistId":"19594","artistName":"Thelonious Monk and John Coltrane","artistSize":"6896112","albumCount":1,"trackCount":1}

Album data excerpt using XML output

<item>
  <artistId>19594</artistId>
  <artistName>Thelonious Monk and John Coltrane</artistName>
  <artistSize>6896112</artistSize>
  <albumCount>1</albumCount>
  <trackCount>1</trackCount>
</item>

Evaluating JSON results ↩

If using Javascript, JSON results may be evaluated directly:

var req = new XMLHttpRequest();

<set up request and make call>

var result = eval('('+req.responseText+')');

JSON callback function ↩

By specifying a callback function as “callback=function” when output=json, you can easily have a local function automatically called with the JSON result passed as a single parameter. For example, the request:

http://ws.mp3tunes.com/api/v1/albumData?output=json&sid=<sid>&type=artist&artist_id=19594&callback=displayArtist

will return:

displayArtist({"artistId":"19594","artistName":"Thelonious Monk and John Coltrane","artistSize":"6896112","albumCount":1,"trackCount":1})

which, when passed to the Javascript eval() function, will cause the function displayArtist() to be called with the result object. A simple example of how this displayArtist callback function might look:

function displayArtist(artistObj) {
    alert("You have " + artistmObj.albumCount + " album(s) by " + artistObj.artistName + " in your locker.");
}

Valid characters in callback function names include:

characters (A-Z, a-z)
numbers (0-9)
period (.)
underscore (_)
brackets ([ and ]) – brackets must be URL encoded

Example of a simple function - will call displayArtist(obj)

...&callback=displayArtist

Example of member function of an object - will call some_object.display_artist(obj)

...&callback=some_object.display_artist

Example of array of functions in an object - will call someObject.callbackArray[0](obj)

...&callback=someObject.callbackArray%5B0%5D

If a specified callback function contains invalid characters, the callback function will not be used in the output.

New Features in Music API v1 ↩

The v1 API is an evolutionary improvement over the v0 API. We will likely continue adding features to the v1 API, however any future changes to the v1 API will not break backward compatibility with the v1 API as it was initially published. Any changes made to the v1 API will be listed here.

Changes between the v0 and v1 API:

lockerData
- support for browse “tokens” – the ability to browse data based on first letter of result data
- ability to break results into sets of specified size
  - artist results
  - album results
  - track results
- ability to retrieve tokens for
  - artist results
  - album results
  - track results
- different URLs for retrieving a track vs. playing a track
- album count and track count in artist data
lockerSearch - new call
- search for artists/albums/tracks within a locker
- ability to break results into sets of specified size
  - artist results
  - album results
  - track results
lockerDelete - new call
playlist management - new functionality
- add / edit / delete playlists
- add / remove / re-order tracks in playlists

The new v1 API calls are accessed with the v1 URL. Example: http://ws.mp3tunes.com/api/v1/….

If you are migrating an application from the v0 API to v1, more details regarding any differences that break backward compatibility are noted where appropriate.

Authentication ↩

The login method attempts to authenticate the received user credentials and setup a session to be used with all subsequent requests. On success the ‘status’ parameter is set to 1, and a valid session id is returned. If authentication fails the ‘status’ parameter is set to 0, and the ‘errorMessage’ parameter is populated with appropriate error messages detailing what caused the call to fail.

Since the login call involves sending users login credentials to MP3tunes servers, the request should be made over SSL to shop.mp3tunes.com.

Parameters ↩

username (required) - A valid MP3tunes account username.
password (required) - A valid MP3tunes account password.
partner_token (required) - A Partner Token is used to uniquely identify and authenticate all entities using API’s to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

Example request ↩

https://shop.mp3tunes.com/api/v1/login?output=xml&username=user@example.com&password=password&partner_token=<partner token>

Example result ↩

<mp3tunes>
  <status>1</status>
  <session_id>xxx2188b626c678a42a681cfc5d36xxx</session_id>
  <username>user@example.com</username>
  <errorMessage />
</mp3tunes>

The session_id value should be used for all other requests as the “sid” parameter.

accountData ↩

The accountData method retrieves information about a user account. This method will tell you what subscription level a user account has as well as the users’ email address, name, and nickname.

Parameters ↩

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
output (optional) - Your preferred output format. These include xml, and json.

Example request ↩

http://ws.mp3tunes.com/api/v1/accountData?output=xml&sid=<sid>

Example result ↩

<mp3tunes>
  <user>
    <email>user@example.com</email>
    <nickName>User Nickname</nickName>
    <firstName>First</firstName>
    <lastName>Last</lastName>
    <maxLockerSize>-1</maxLockerSize>
    <currentLockerSize>54226434</currentLockerSize>
    <maxFileSize>52428800</maxFileSize>
    <subscriptions>
      <item>
        <name>user_locker_annual</name>
        <description>Premium</description>
        <activateDate>2007-03-27 15:17:08</activateDate>
        <expireDate>2008-03-27 15:17:08</expireDate>
      </item>
    </subscriptions>
    <lockerType>premium</lockerType>
    <expired>0</expired>
  </user>
</mp3tunes>

Accessing User Lockers and Playing Tracks ↩

lastUpdate ↩

Description ↩

Many external applications prefer to cache user locker data locally in order to optimize performance. By caching data retrieved from the MP3tunes Music API, an application can greatly increase response times within the application, therefore improving the user experience. In order to effectively cache user data locally, it is necessary to know when that data is no longer valid due to changes the user has made in a locker.

The lastUpdate call can be used to determine if data cached locally is still valid. A request to lastUpdate will return quickly, more quickly that just about any other call, and the size of the response is small. A high level view of a caching strategy would be:

Fetch the last update time from the MP3tunes API
Compare that time with locally stored version of the last update time. If this is the first call, the local version will be empty or 0.
If last update time just fetched is more recent, fetch user data, cache it locally, and store the last update time.
If last update time just fetched matches the value stored, use the user data cached locally.

There are actually multiple last update times in the MP3tunes system:

locker - last time that any tracks were added, deleted, tuned up, moved to trash, etc.
playlist - last time that any playlists were modified – this does not affect PlayMix data
preferences - last time that preferences were changed

An application can therefore make an intelligent decision as to how much data should be invalidated in a local cache and subsequently fetched again from MP3tunes. For example, if a user playlist last update time changes, the application would only have to fetch playlist data. Any other locker data (artists, albums, etc.) previously cached would still be valid.

Parameters ↩

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
type (required) - Specifies the type of last update time to return. See the above list for valid types.
output (optional) - Your preferred output format. These include xml, and json.

Example request ↩

http://ws.mp3tunes.com/api/v1/lastUpdate?output=xml&sid=<session ID>&type=locker

Example result ↩

<mp3tunes>
  <status>1</status>
  <type>locker</type>
  <timestamp>1201830743</timestamp>
</mp3tunes>

lockerData ↩

Description ↩

The lockerData method allows you to retrieve the contents of a user’s locker. Artist, album, track and playlist data can be retrieved. The v1 API adds the ability to control the amount of data retrieved in any request, which is helpful when developing on a platform with limited resources.

Differences from v0 lockerData results ↩

All lockerData results now contain a “summary” object or node that includes:

type - type of request being made
artistId - if used, the artist ID passed in the request
albumId - if used, the album ID passed in the request
playlistId - if used, the playlist ID passed in the request
token - if used, the token passed in the request
count - if used, the maximum number of results to be returned
set - if used, the result set number to be returned
totalResults - total number of results generated by the request
totalResultSets - if count and set used, the total number of result sets in the result

All lockerData results are now contained in a top level “list” object or node

Previously, in v0 lockerData calls, only results where type=track were contained within a top level “list” object or node (trackList). All other result sets were contained within the top level “mp3tunes” object or node. For v1 lockerData calls, all result sets are consistently contained within an appropriately named “list” object or node.

type=artist - all results are contained within an “artistList” object or node
type=album - all results are contained within an “albumList” object or node
type=track - all results are contained within a “trackList” object or node (unchanged from v0)
type=playlist - all results are contained within a “playlistList” object or node
type=playmix - all results are contained within a “playlistList” object or node
type=artist_token - all results are contained within a “tokenList” object or node
type=album_token - all results are contained within a “tokenList” object or node
type=track_token - all results are contained within a “tokenList” object or node

A note about type=playlist and type=playmix

This is essentially the same call, with type=playmix returning a specialized list of PlayMix lists. By default PlayMix lists are returned in type=playlist results. To retrive only PlayMix lists, use type=playmix instead of type=playlist. Additionally, a noplaymix=1 parameter can be added to a type=playlist call to exclude PlayMix lists from user created playlist resluts.

In summary, there are two options with respect to retrieving user created playlists and system generated PlayMix lists:

Use only type=playlist lockerData calls to retrive user created playlists and PlayMix lists in the same call
Use type=playlist with the noplaymix=1 parameter to retrive user created playlists, and type=playmix to retrive PlayMix lists

Parameters ↩

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
type (required) - Specifies the type of data to return. See the above list for valid types.
output (optional) - Your preferred output format. These include xml, and json.
count (optional) - Maximum number of results to be returned in a result set.
set (optional) - The result set number to retrieve, note that set numbers are 0 based.
album_id (optional) - Used when type=track to filter list of tracks by album. To retrieve a list of albums, set type=album.
artist_id (optional) - Used when type=album to filter list of albums by artist, or when type=track to filter list of tracks by artist. To retrieve a list of artists, set type=artist.
playlist_id (optional) - Used when type=track to filter list of tracks by playlist. To retrieve a list of playlists, set type=playlist or type=playmix.
noplaymix=1 (optional) - Used when type=playlist to exclude PlayMix lists. This would be used in combination with type=playmix in order to break out user created playlists separately from PlayMix lists.

Example requests ↩

Example request - artist data

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<sid>&type=artist

Example result - artist data

<mp3tunes>
  <summary>
    <type>artist</type>
    <totalResults>7</totalResults>
  </summary>
  <artistList>
    <item>
      <artistId>9864</artistId>
      <artistName>Django Reinhardt</artistName>
      <artistSize>55936279</artistSize>
      <albumCount>1</albumCount>
      <trackCount>10</trackCount>
    </item>
    <item>
      <artistId>274</artistId>
      <artistName>Jimi Hendrix</artistName>
      <artistSize>3681749</artistSize>
      <albumCount>4</albumCount>
      <trackCount>5</trackCount>
    </item>
    <item>
      <artistId>43</artistId>
      <artistName>Miles Davis Quintet</artistName>
      <artistSize>7033334</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
    ...
  </artistList>
</mp3tunes>

Example request - album data for artist

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<sid>&type=album&artist_id=43

Example result - album data for artist

<mp3tunes>
  <summary>
    <type>album</type>
    <artistId>43</artistId>
    <totalResults>1</totalResults>
  </summary>
  <albumList>
    <item>
      <albumId>56</albumId>
      <albumTitle>Relaxin&apos; With The Miles Davis</albumTitle>
      <artistId>43</artistId>
      <artistName>Miles Davis Quintet</artistName>
      <trackCount>1</trackCount>
      <albumSize>7033334</albumSize>
      <releaseDate />
      <purchaseDate />
      <hasArt>2</hasArt>
    </item>
  </albumList>
</mp3tunes>

Example request - track data for album

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<sid>&type=track&album_id=56

Example result - track data for album

Note the playURL and downloadURL result data. These URLs can be used to stream (via http progressive download) or download a track.

<mp3tunes>
  <albumData>
    <albumId>56</albumId>
    <albumTitle>Relaxin&apos; With The Miles Davis</albumTitle>
    <artistId>43</artistId>
    <artistName>Miles Davis Quintet</artistName>
    <trackCount>1</trackCount>
    <albumSize>7033334</albumSize>
    <releaseDate />
    <purchaseDate />
    <hasArt>2</hasArt>
  </albumData>
  <trackList>
    <item>
      <trackId>423</trackId>
      <trackTitle>Oleo</trackTitle>
      <trackNumber>4</trackNumber>
      <trackLength />
      <trackFileName>04 Oleo.mp3</trackFileName>
      <trackFileKey>7c653bfdfd2e93dc5e04140c0b5b7287</trackFileKey>
      <trackFileSize>7033334</trackFileSize>
      <downloadURL>http://content.test.mp3tunes.com/storage/lockerget/7c653bfdfd2e93dc5e04140c0b5b7287?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</downloadURL>
      <playURL>http://content.test.mp3tunes.com/storage/lockerplay/7c653bfdfd2e93dc5e04140c0b5b7287?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</playURL>
      <albumId>56</albumId>
      <albumTitle>Relaxin&apos; With The Miles Davis</albumTitle>
      <albumYear>1956</albumYear>
      <artistId>43</artistId>
      <artistName>Miles Davis Quintet</artistName>
      <albumArtURL>http://content.test.mp3tunes.com/storage/albumartget/7c653bfdfd2e93dc5e04140c0b5b7287?sid=d102188b626c678a42a681cfc5d3685f</albumArtURL>
    </item>
  </trackList>
  <summary>
    <type>track</type>
    <albumId>56</albumId>
    <totalResults>1</totalResults>
  </summary>
</mp3tunes>

Example request - playlist data

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<sid>&type=playlist

Example result - playlist data

Note the three “hard coded” playlists that display first, with non-numeric playlistId values:

RANDOM_TRACKS
NEWEST_TRACKS
RECENTLY_PLAYED

These playlists will be present in every call where type=playlist.

Note the presence of both “playlistTitle” and “title” values. The “title” value is considered deprecated, but is still part of the data for backward compatibility. The “title” valid may be removed in a future version of the MP3tunes API.

The “dateModified” value is reserved for future use, and may or may not contain a value.

The “playlistSize” value will not be present for the three hard coded playlists, as these playlists are dynamic. The playlist size may change between the time the list of playlists is retrieved and the when playlist tracks are retrieved.

<mp3tunes>
  <summary>
    <type>playlist</type>
    <totalResults>4</totalResults>
  </summary>
  <playlistList>
    <item>
      <playlistId>RANDOM_TRACKS</playlistId>
      <playlistTitle>Random tracks</playlistTitle>
      <title>Random tracks</title>
      <fileName>RANDOM_TRACKS</fileName>
      <fileCount>100</fileCount>
      <dateModified />
      <playlistSize />
    </item>
    <item>
      <playlistId>NEWEST_TRACKS</playlistId>
      <playlistTitle>Newest tracks</playlistTitle>
      <title>Newest tracks</title>
      <fileName>NEWEST_TRACKS</fileName>
      <fileCount>50</fileCount>
      <dateModified />
      <playlistSize />
    </item>
    <item>
      <playlistId>RECENTLY_PLAYED</playlistId>
      <playlistTitle>Recently Played</playlistTitle>
      <title>Recently played</title>
      <fileName>RECENTLY_PLAYED</fileName>
      <fileCount>50</fileCount>
      <dateModified />
      <playlistSize />
    </item>
    <item>
      <playlistId>192402</playlistId>
      <playlistTitle>Warren Zevon / Stand in the Fire</playlistTitle>
      <title>Warren Zevon / Stand in the Fire</title>
      <fileName>WarrenZevon-StandintheFire.m3u</fileName>
      <fileCount>14</fileCount>
      <dateModified />
      <playlistSize>86669699</playlistSize>
    </item>
  </playlistList>
</mp3tunes>

Example request - track data for playlist

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<sid>&type=track&playlist_id=192402

Example result - track data for playlist

<mp3tunes>
  <albumData />
  <trackList>
    <item>
      <trackId>12599149</trackId>
      <trackTitle>Stand In The Fire (2007 Remastered Live LP Version</trackTitle>
      <trackNumber>1</trackNumber>
      <trackLength>217401.625</trackLength>
      <trackFileName>603497997770-001.mp3</trackFileName>
      <trackFileKey>23b593ff77aa33f349b6b5a341c42cca</trackFileKey>
      <trackFileSize>5217639</trackFileSize>
      <downloadURL>http://content.test.mp3tunes.com/storage/lockerget/23b593ff77aa33f349b6b5a341c42cca?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</downloadURL>
      <playURL>http://content.test.mp3tunes.com/storage/lockerplay/23b593ff77aa33f349b6b5a341c42cca?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</playURL>
      <albumId>329981</albumId>
      <albumTitle>Stand in the Fire</albumTitle>
      <albumYear>1980</albumYear>
      <artistId>1785</artistId>
      <artistName>Warren Zevon</artistName>
    </item>
    ...
    <item>
      <trackId>12599173</trackId>
      <trackTitle>Hasten Down The Wind (Previously Unissued Live LP</trackTitle>
      <trackNumber>14</trackNumber>
      <trackLength>273826.125</trackLength>
      <trackFileName>603497997770-014.mp3</trackFileName>
      <trackFileKey>1ae88ca03e4f08d8abd0a622812dc06a</trackFileKey>
      <trackFileSize>6571827</trackFileSize>
      <downloadURL>http://content.test.mp3tunes.com/storage/lockerget/1ae88ca03e4f08d8abd0a622812dc06a?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</downloadURL>
      <playURL>http://content.test.mp3tunes.com/storage/lockerplay/1ae88ca03e4f08d8abd0a622812dc06a?sid=d102188b626c678a42a681cfc5d3685f&amp;partner_token=</playURL>
      <albumId>329981</albumId>
      <albumTitle>Stand in the Fire</albumTitle>
      <albumYear>1980</albumYear>
      <artistId>1785</artistId>
      <artistName>Warren Zevon</artistName>
    </item>
  </trackList>
  <summary>
    <type>track</type>
    <playlistId>192402</playlistId>
    <totalResults>14</totalResults>
  </summary>
</mp3tunes>

Filter results by browse tokens ↩

Description

For browsing large data set results, it may helpful to retrieve results based on the first letter of the result. For instance, a list of artists might be broken down as:

A
B
- Bad Company
- Beatles
- Bob Dylan
- Boston
C
D

New parameters

token - include result values beginning with this token only

Applies to

type=artist (token based on artist name)
type=album (token based on album title)
type=track (token based on track title)

Example request

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<session ID>&type=artist&token=B

Example result

<mp3tunes>
  <summary>
    <type>artist</type>
    <token>B</token>
    <totalResults>56</totalResults>
  </summary>
  <artistList>
    <item>
      <artistId>14</artistId>
      <artistName>Backbeat Acid Jazz Allstars</artistName>
      <artistSize>7777516</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
    <item>
      <artistId>89</artistId>
      <artistName>Bad Religion</artistName>
      <artistSize>2783360</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
    <item>
      <artistId>116</artistId>
      <artistName>Barbra Streisand</artistName>
      <artistSize>4957500</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
    <item>
      <artistId>13187</artistId>
      <artistName>Barney Kessel</artistName>
      <artistSize>60082846</artistSize>
      <albumCount>2</albumCount>
      <trackCount>11</trackCount>
    </item>
    <!-- more results removed -->
  </artistList>
</mp3tunes>

Retrieve list of browse tokens ↩

Description

In order to enable efficient presentation of browsing results by token, it may be helpful to obtain a list of tokens for which there is at least one result value.

New “type” parameter values

artist_token
album_token
track_token

Example request

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<session ID>&type=artist_token

Example result

<mp3tunes>
  <summary>
    <type>artist_token</type>
    <totalResults>27</totalResults>
  </summary>
  <tokenList>
    <item>
      <token>-</token>
      <count>3</count>
    </item>
    <item>
      <token>A</token>
      <count>42</count>
    </item>
    <item>
      <token>B</token>
      <count>56</count>
    </item>
    <item>
      <token>C</token>
      <count>41</count>
    </item>
    <item>
      <token>D</token>
      <count>50</count>
    </item>
    <!-- more results removed -->
  </tokenList>
</mp3tunes>

Retrieve results in sets of defined sizes ↩

Description

In some instances, it may be desirable to limit the size of a result set due to limited availble memory and/or large locker sizes. It is now possible to retrieve lockerData results in multiple sets of a defined size.

New parameters

count - maximum number of results to be returned in a result set
set - the result set number to retrieve, note that set numbers are 0 based

Applies to

type=artist
type=album
type=track

Example request

http://ws.mp3tunes.com/api/v1/lockerData?output=xml&sid=<session ID>&type=artist&count=5&set=0

Example result

<mp3tunes>
  <summary>
    <type>artist</type>
    <totalResults>663</totalResults>
    <set>0</set>
    <count>5</count>
    <totalResultSets>133</totalResultSets>
  </summary>
  <artistList>
    <item>
      <artistId>13435</artistId>
      <artistName>&apos;Papa&apos; John DeFrancesco</artistName>
      <artistSize>85896476</artistSize>
      <albumCount>1</albumCount>
      <trackCount>9</trackCount>
    </item>
    <item>
      <artistId>144</artistId>
      <artistName>.38 Special</artistName>
      <artistSize>4361950</artistSize>
      <albumCount>2</albumCount>
      <trackCount>2</trackCount>
    </item>
    <item>
      <artistId>85</artistId>
      <artistName>3 Doors Down</artistName>
      <artistSize>22680020</artistSize>
      <albumCount>2</albumCount>
      <trackCount>5</trackCount>
    </item>
    <item>
      <artistId>145</artistId>
      <artistName>A Perfect Circle</artistName>
      <artistSize>3872809</artistSize>
      <albumCount>4</albumCount>
      <trackCount>19</trackCount>
    </item>
    <item>
      <artistId>304419</artistId>
      <artistName>A Touch of Jazz</artistName>
      <artistSize>3474478</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
  </artistList>
</mp3tunes>

Different URLs for retrieving a track vs. playing a track ↩

Description

There is now a separate URL to be used for playing a track (via http progressive download), as opposed to fetching a track. Use the playURL value to play a track, instead of the downloadURL value. There is no difference in the parameters or the result, however using the “play” version (playURL) will increment the internal play count value for the track.

See example lockerData call.

The playURL value has also been added to the v0 lockerData API call when type=track.

lockerSearch ↩

Description ↩

The lockerSearch call allows for searching a user’s locker for specific artist, album or track content. Any combination of an artist, album, or track search can be executed in a single request. A lockerSearch result contains a summary section similar to the lockerData result summary, with some minor differences. Artist, album and track result data is identical to lockerData artist, album and track result data.

Parameters ↩

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
type (required) - Type options consist of “artist”, “album”, or “track”. Any combination of comma separated type values can be passed in a single request.
s (required) - The URL encoded string to use in the search.
output (optional) - Your preferred output format. These include xml, and json.
count (optional) - maximum number of results to be returned in a result set.
set (optional) - the result set number to retrieve, note that set numbers are 0 based.

Results ↩

Result summary

type - Type of request being made (the value passed in the request).
count - If used, the maximum number of results to be returned.
set - If used, the result set number to be returned.
totalResults - Total number of results generated by the request, separated by artist, album and track result. Result counts will only be included for “type” values passed in the request.
totalResultSets - If count and set used, the total number of result sets in the result. If multiple “type” values were passed in the request, the type with the largest amount of results will determine the number of result sets.

Example requests ↩

Example request - searching for artists containing “wave” in the artist name

http://ws.mp3tunes.com/api/v1/lockerSearch?output=xml&sid=<session ID>&type=artist&s=wave

Example result

<mp3tunes>
  <summary>
    <type>artist</type>
    <totalResults>
      <artist>1</artist>
    </totalResults>
  </summary>
  <artistList>
    <item>
      <artistId>2905</artistId>
      <artistName>Katrina &amp; The Waves</artistName>
      <artistSize>6317621</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
  </artistList>
</mp3tunes>

Example request - searching for artists, albums or tracks containing “wave”, max of 50 results per set

http://ws.mp3tunes.com/api/v1/lockerSearch?output=xml&sid=<session ID>&type=artist,album,track&s=wave&count=50&set=0

Example result

<mp3tunes>
  <summary>
    <type>artist,album,track</type>
    <totalResults>
      <artist>1</artist>
      <album>2</album>
      <track>4</track>
    </totalResults>
    <set>0</set>
    <count>50</count>
    <totalResultSets>1</totalResultSets>
  </summary>
  <artistList>
    <item>
      <artistId>2905</artistId>
      <artistName>Katrina &amp; The Waves</artistName>
      <artistSize>6317621</artistSize>
      <albumCount>1</albumCount>
      <trackCount>1</trackCount>
    </item>
  </artistList>
  <albumList>
    <item>
      <albumId>68540</albumId>
      <albumTitle>Permanent Waves</albumTitle>
      <artistId>733</artistId>
      <artistName>Rush</artistName>
      <trackCount>1</trackCount>
      <albumSize>4403605</albumSize>
      <releaseDate />
      <purchaseDate />
      <hasArt>0</hasArt>
    </item>
    <item>
      <albumId>20968</albumId>
      <albumTitle>Wave</albumTitle>
      <artistId>5620</artistId>
      <artistName>Antonio Carlos Jobim</artistName>
      <trackCount>10</trackCount>
      <albumSize>76175514</albumSize>
      <releaseDate />
      <purchaseDate />
      <hasArt>0</hasArt>
    </item>
  </albumList>
  <trackList>
    <item>
      <trackId>8271292</trackId>
      <trackTitle>Even the Waves</trackTitle>
      <trackNumber>0</trackNumber>
      <trackLength>393020.1875</trackLength>
      <trackFileName>Even_the_Waves.mp3</trackFileName>
      <trackFileKey>fad1efc63f6915e6f888b907c00f9066</trackFileKey>
      <trackFileSize>6288323</trackFileSize>
      <downloadURL>http://ws.mp3tunes.com/storage/lockerget/fad1efc63f6915e6f888b907c00f9066?sid=<session ID>&amp;partner_token=</downloadURL>
    <playURL>http://ws.mp3tunes.com/storage/lockerplay/fad1efc63f6915e6f888b907c00f9066?sid=<session ID>&amp;partner_token=</playURL>
      <albumId>1321138</albumId>
      <albumTitle>Unknown</albumTitle>
      <albumYear />
      <artistId>21</artistId>
      <artistName>Chroma Key</artistName>
    </item>
    <item>
      <trackId>57913</trackId>
      <trackTitle>Wave</trackTitle>
      <trackNumber>1</trackNumber>
      <trackLength>177035.225</trackLength>
      <trackFileName>01 Wave.mp3</trackFileName>
      <trackFileKey>a891bcde3f823884e82868131444001b</trackFileKey>
      <trackFileSize>7081409</trackFileSize>
      <downloadURL>http://ws.mp3tunes.com/storage/lockerget/a891bcde3f823884e82868131444001b?sid=<session ID>&amp;partner_token=</downloadURL>
      <playURL>http://ws.mp3tunes.com/storage/lockerplay/a891bcde3f823884e82868131444001b?sid=<session ID>&amp;partner_token=</playURL>
      <albumId>20968</albumId>
      <albumTitle>Wave</albumTitle>
      <albumYear>1967</albumYear>
      <artistId>5620</artistId>
      <artistName>Antonio Carlos Jobim</artistName>
    </item>
    <item>
      <trackId>310</trackId>
      <trackTitle>Wave</trackTitle>
      <trackNumber>6</trackNumber>
      <trackLength />
      <trackFileName>06 Wave.mp3</trackFileName>
      <trackFileKey>c51c72a04bea699e65af21342a67aa52</trackFileKey>
      <trackFileSize>6394810</trackFileSize>
      <downloadURL>http://ws.mp3tunes.com/storage/lockerget/c51c72a04bea699e65af21342a67aa52?sid=<session ID>&amp;partner_token=</downloadURL>
      <playURL>http://ws.mp3tunes.com/storage/lockerplay/c51c72a04bea699e65af21342a67aa52?sid=<session ID>&amp;partner_token=</playURL>
      <albumId>43</albumId>
      <albumTitle>Soft &amp; Mellow</albumTitle>
      <albumYear>1978</albumYear>
      <artistId>31</artistId>
      <artistName>Herb Ellis</artistName>
    </item>
    <item>
      <trackId>334</trackId>
      <trackTitle>Wave</trackTitle>
      <trackNumber>9</trackNumber>
      <trackLength>317132.75276939</trackLength>
      <trackFileName>09 Wave.mp3</trackFileName>
      <trackFileKey>de12247398eba106aaed73792bbe49fc</trackFileKey>
      <trackFileSize>6523942</trackFileSize>
      <downloadURL>http://ws.mp3tunes.com/storage/lockerget/de12247398eba106aaed73792bbe49fc?sid=<session ID>&amp;partner_token=</downloadURL>
      <playURL>http://ws.mp3tunes.com/storage/lockerplay/de12247398eba106aaed73792bbe49fc?sid=<session ID>&amp;partner_token=</playURL>
      <albumId>46</albumId>
      <albumTitle>Favorites</albumTitle>
      <albumYear>2002</albumYear>
      <artistId>34</artistId>
      <artistName>Jazz Mandolin</artistName>
    </item>
  </trackList>
</mp3tunes>

Playlist Management ↩

Playlist management is a very important aspect of organizing a large music collection. The MP3tunes API playlist management functions allow for complete manipulation of a user’s playlists.

playlistAdd ↩

Used to create a new playlist. A list of track file keys can optionally be passed in the request, allowing a new playlist to be created and populated with tracks in one call.

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
title (required) - Playlist title.
keys (optional) - Comma separated list of file keys to add to new playlist.

Example request

Creating a new playlist.

 http://ws.mp3tunes.com/api/v1/playlistAdd?output=xml&sid=<session ID>&title=Wave+Files

Creating a new playlist and populating it with tracks.

 http://ws.mp3tunes.com/api/v1/playlistAdd?output=xml&sid=<session ID>&title=Wave+Files&keys=fad1efc63f6915e6f888b907c00f9066,a891bcde3f823884e82868131444001b,c51c72a04bea699e65af21342a67aa52,123BogusKey

Note: An invalid file key is being used in this example to illustrate how invalid keys are handled in the result.

Example result

Note that the number of tracks successfully added is provided, as well as the file keys that were successfully added to the new playlist. If any file keys are unable to be verified, it will be listed in invalidKeys.

Playlist created with no tracks.

<mp3tunes>
  <status>1</status>
  <playlistId>89041</playlistId>
  <tracksAdded>0</tracksAdded>
  <validKeys />
  <invalidKeys />
</mp3tunes>

Playlist created containing three tracks.

<mp3tunes>
  <status>1</status>
  <playlistId>89041</playlistId>
  <tracksAdded>3</tracksAdded>
  <validKeys>
    <item>fad1efc63f6915e6f888b907c00f9066</item>
    <item>a891bcde3f823884e82868131444001b</item>
    <item>c51c72a04bea699e65af21342a67aa52</item>
  </validKeys>
  <invalidKeys>
    <item>123BogusKey</item>
  </invalidKeys>
</mp3tunes>

playlistDelete ↩

Used to delete an existing playlist.

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
playlist_id (required) - A valid playlist ID.

Example request

 http://ws.mp3tunes.com/api/v1/playlistDelete?output=xml&sid=<session ID>&playlist_id=89401

Example result

<mp3tunes>
  <status>1</status>
  <playlistsDeleted>1</playlistsDeleted>
</mp3tunes>

playlistEdit ↩

Used to edit the title of a playlist.

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
playlist_id (required) - A valid playlist ID.
title (required) - A new title for the playlist.

Example request

 http://ws.mp3tunes.com/api/v1/playlistEdit?output=xml&sid=<session ID>&playlist_id=89401&title=Ride+the+Wave

Example result

<mp3tunes>
  <status>1</status>
</mp3tunes>

playlistTrackAdd ↩

Used to add tracks to an existing playlist.

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
playlist_id (required) - A valid playlist ID.
file_key (required) - A valid track file key.
position (optional) - Position of the new track in the playlist (defaults to end of list)

Note that playlist positions start with 1, not 0.

Example request

Add a track to the end of a playlist.

 http://ws.mp3tunes.com/api/v1/playlistTrackAdd?output=xml&sid=<session ID>&playlist_id=89041&file_key=fad1efc63f6915e6f888b907c00f9066

Add a track to a playlist in position 1 (the beginning of the list). If an invalid position is provided, the track will be added to the end of the playlist.

 http://ws.mp3tunes.com/api/v1/playlistTrackAdd?output=xml&sid=<session ID>&playlist_id=89041&file_key=a891bcde3f823884e82868131444001b&position=1

Example result

The result is the same whether a position is provided in the request or not.

<mp3tunes>
  <status>1</status>
  <playlistId>89041</playlistId>
  <trackFileKey>fad1efc63f6915e6f888b907c00f9066</trackFileKey>
</mp3tunes>

playlistTrackDelete ↩

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
playlist_id (required) - A valid playlist ID.
file_key (required) - A valid track file key.

Example request

 http://ws.mp3tunes.com/api/v1/playlistTrackDelete?output=xml&sid=<session ID>&&playlist_id=89041&file_key=fad1efc63f6915e6f888b907c00f9066

Example result

<mp3tunes>
  <status>1</status>
  <playlistId>89041</playlistId>
  <trackFileKey>fad1efc63f6915e6f888b907c00f9066</trackFileKey>
</mp3tunes>

playlistTrackReorder ↩

Parameters

sid (required) - A valid session id, received from the “login” method.
partner_token (required) - A valid partner token.
playlist_id (required) - A valid playlist ID.
file_key (required) - A valid track file key.
position (required) - Desired position for the track in the playlist.

Example request

 http://ws.mp3tunes.com/api/v1/playlistTrackReorder?output=xml&sid=<session ID>&&playlist_id=89041&file_key=a891bcde3f823884e82868131444001b&position=1

If an invalid position is provided, the call with fail with an appropriate error message.

Example result

Valid position provided.

<mp3tunes>
  <status>1</status>
  <errorMessage />
  <playlistId>89041</playlistId>
  <trackFileKey>a891bcde3f823884e82868131444001b</trackFileKey>
  <position>1</position>
</mp3tunes>

Invalid position provided (position of 5 specified, but playlist has less than 5 tracks).

<mp3tunes>
  <status>0</status>
  <errorMessage>Invalid playist position</errorMessage>
  <playlistId>89045</playlistId>
  <trackFileKey>a891bcde3f823884e82868131444001b</trackFileKey>
  <position>5</position>
</mp3tunes>

lockerDelete ↩

Description ↩

The lockerDelete call is a new addition to storage API functionality which allows moving a locker file to “trash” and also allows for removing a file from the trash. Trash must be emptied using the web UI.

Syntax ↩

Moving a file into trash

http://content.mp3tunes.com/storage/lockerDelete/<file key>?sid=<session ID>

Restoring a file from trash

http://content.mp3tunes.com/storage/lockerDelete/<file key>?sid=<session ID>&action=restore

Results

A successful call to lockerDelete will return a 200 error code and the response content of “OK”. An unsuccessful call to lockerDelete will return an appropriate HTTP error code (401, 404, etc.) and contain an error message in the “X-MP3tunes-ErrorString” response header.

Example header from an unsuccessful call:

HTTP/1.1 404 File not found
Date: Fri, 25 May 2007 21:58:50 GMT
Server: Apache
X-Powered-By: PHP/5.2.1
X-MP3tunes-ErrorNo: 404002
X-MP3tunes-ErrorString: File key 44a3380ca95cdaffba67efca26f92cxx could not be found
Connection: close
Content-Type: text/html

Note that special handling may be desired for the 503 error indicating the service is currently “read-only”, which means files can be played and fetched from the service, but not modified. Included in the response header is a “Retry-After” value indicating a number of seconds to wait before trying the call again.

HTTP/1.1 503 Service Unavailable.
Date: Fri, 25 May 2007 22:44:05 GMT
Server: Apache
X-Powered-By: PHP/5.2.1
X-MP3tunes-ErrorNo: 503001
X-MP3tunes-ErrorString: Service Unavailable. We are currently performing system maintenance.
Retry-After: 900
Connection: close
Content-Type: text/html

Music Sync ↩

We are still finalizing documentation and procedures for syncing tracks in a locker to a device or computer. The best way to enable a music sync from an external application is to embed our LockerSync functionality directly into that application.

LockerSync: The latest generation of the MP3tunes sync application.
LockerSync XML Interface: LockerSync can be controlled by other applications via either TCP sockets or or a command line interface (CLI). This is currently the only way to implement a music sync action in your application.

Print version

Back to main API page

MP3tunes Music API

Table of Contents

Overview ↩

Music API Version ↩

Current Version

Previous Versions

Technical Resources ↩

API Domains and URLs ↩

Request and Response Formats ↩

Requests format ↩

Response format ↩

Evaluating JSON results ↩

JSON callback function ↩

New Features in Music API v1 ↩

Authentication ↩

login ↩

Parameters ↩

Example request ↩

Example result ↩

accountData ↩

Parameters ↩

Example request ↩

Example result ↩

Accessing User Lockers and Playing Tracks ↩

lastUpdate ↩

Description ↩

Parameters ↩

Example request ↩

Example result ↩

lockerData ↩

Description ↩

Differences from v0 lockerData results ↩

All lockerData results now contain a “summary” object or node that includes:

All lockerData results are now contained in a top level “list” object or node

A note about type=playlist and type=playmix

Parameters ↩

Example requests ↩

Example request - artist data

Example result - artist data

Example request - album data for artist

Example result - album data for artist

Example request - track data for album

Example result - track data for album

Example request - playlist data

Example result - playlist data

Example request - track data for playlist

Example result - track data for playlist

Filter results by browse tokens ↩

Description

New parameters

Applies to

Example request

Example result

Retrieve list of browse tokens ↩

Description

New “type” parameter values

Example request

Example result

Retrieve results in sets of defined sizes ↩

Description

New parameters

Applies to

Example request

Example result

Different URLs for retrieving a track vs. playing a track ↩

Description

lockerSearch ↩

Description ↩

Parameters ↩

Results ↩

Result summary

Example requests ↩

Example request - searching for artists containing “wave” in the artist name

Example result

Example request - searching for artists, albums or tracks containing “wave”, max of 50 results per set

Example result

Playlist Management ↩

playlistAdd ↩

Parameters

Example request