Official 8tracks API v2

Last updated on July 26, 2010

This doc is deprecated. NEW API Doc is at: http://8tracks.com/developers/api

If you have questions, or if you want to get an email when the API changes, please join the 8tracks public API group at:

http://groups.google.com/group/8tracks-public-api

Introduction

This developer API offers a pretty typical RESTful interface and all calls are available in JSON / XML / JSONP. You can pick your format by appending what you need at the end of the URL:

http://8tracks.com/mixes.xml

http://8tracks.com/mixes.jsonp

In this documentation we will show examples of the XML version of the API but you can use any of these 3 formats.

A typical response will look like this:

<response>

<status>200 OK</status>

<errors nil="true"></errors>

<notices nil="true"></notices>

<logged-in>false</logged-in>

<page>1</page>

<per_page>15</per_page>

<total

...

</response>

status: it is the same as the HTTP Status code and is only here to make the API easier to use. You can expect to see the following status codes: 200 OK, 301 Moved Permanently, 302 Moved, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error.

errors: list of errors that occurred during this request.

http://8tracks.com/developers/api

http://groups.google.com/group/8tracks-public-api

notices: list of what happened during the request such as 'logged in successfully'

logged-in: indicates if you are currently logged in

and when look at paginated content:

page: this is the page you're on

per_page: this is how many items there are per page.

total-entries: this is how many items there are, total.

In this documentation we will explore look at how to:

- Find and listen to mixes

- Get data on a user

- Update user data (with authentication)

Authentication

Verify credentials

Bad password

curl --request POST -d "login=remi&password=bad" http://8tracks.com/sessions.xml

<response>


<status>422 Unprocessable Entity</status>

<errors>

<error>Your login was unsuccessful</error>

</errors>


</response>

Good Password

curl --request POST -d "login=remi&password=good" http://8tracks.com/sessions.xml

<response>

<logged-in>true</logged-in>



<current-user>

<slug>remi</slug>

<next-mix-prefs>ask</next-mix-prefs>

<id>1</id>

<popup-prefs>ask</popup-prefs>

<avatar-urls>

<sq56>http://cf1.8tracks.us/avatars/000/000/001/12363.sq56.jpg</sq56>



<max200>http://cf1.8tracks.us/avatars/000/000/001/12363.max200.jpg</max200>

</avatar-urls>

<login>remi</login>

<followed-by-current-user>false</followed-by-current-user>

</current-user>

<notices>

<notice>You are now logged in as remi</notice>

</notices>

</response>

Basic Authentication

Once you verify user credentials, you can use Basic Authentication for any call requiring authentication. If you use incorrect credentials:

curl -u remi:bad --request POST -d "" http://8tracks.com/mixes/14/toggle_like.xml

<response> <logged_in>false</logged_in> <status>401 Unauthorized</status> <errors nil="true"></errors> <notices> <notice>You must log in to do this.</notice> </notices></response>

This is what you get when you use correct credentials:

curl -u remi:bad --request POST -d "" http://8tracks.com/mixes/14/toggle_like.xml

<response> <logged_in>true</logged_in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> ...</response>

Mix Search

The simplest call possible is to get the latest 10 mixes:

curl http://8tracks.com/mixes.xml

<response>



<page>1</page>

<per-page>8</per-page>


<total-entries>99880</total-entries>

<mixes>

<mix>

<slug>all-the-living-are-dead-and-the-dead-are-all-living</slug>

<name>All the living are dead, and the dead are all living. </name>

<published>true</published>

<cover_urls>

<sq56>http://cf3.8tracks.us/mix_covers/000/125/363/79524.sq56.jpg</sq56>


<original>http://cf3.8tracks.us/mix_covers/000/125/363/79524.original.jpg</original>

<max200>http://cf3.8tracks.us/mix_covers/000/125/363/79524.max200.jpg</max200>


<max133w>http://cf3.8tracks.us/mix_covers/000/125/363/79524.max133w.jpg</max133w>

</cover_urls>

<id>125363</id>

<liked-by-current-user>false</liked-by-current-user>

<user>

<slug>violentlyoppossed</slug>

<id>72787</id>

<avatar-urls>





</avatar-urls>

<login>violentlyoppossed</login>


</user>

<tag-list-cache>rock,pop</tag-list-cache>

<plays-count>0</plays-count>

<description>Songs for regrets, or lack thereof.

Twelve tracks including music by Beach House, Belle & Sebastian and Stars.</description>

<path>/violentlyoppossed/all-the-living-are-dead-and-the-dead-are-all-living</path>

<restful-url>http://8tracks.com/mixes/125363</restful-url>

<first-published-at>2010-06-12T22:22:28Z</first-published-

at>

</mix>

...

</mixes>


</response>

To view the next page of results specifiy the page number:

http://8tracks.com/mixes.xml?page=2

NOTE: The page parameter works for all paginated API calls.

To search or filter the results append the criteria:

curl http://8tracks.com/mixes.xml?q=miles+davis

Or to list mixes by tag, use the tag parameter:

curl http://8tracks.com/mixes.xml?tag=jazz

You can also order results in 4 ways:

curl http://8tracks.com/mixes.xml?tag=jazz&sort=recent

curl http://8tracks.com/mixes.xml?tag=jazz&sort=popular

curl http://8tracks.com/mixes.xml?tag=jazz&sort=hot

curl http://8tracks.com/mixes.xml?tag=jazz&sort=random

And change the number of entries per page:

curl http://8tracks.com/mixes.xml?per_page=20

For information on a single mix:

curl http://8tracks.com/mixes/1002.xml

<response>



<mix>

<slug>thrillists-mitchell-frank-sunset-junction-mix</slug>

<name>Thrillist's Mitchell Frank Sunset Junction Mix</name>


<cover_urls>

<sq56>/images/mix_covers/sq56.gif</sq56>


<original>/images/mix_covers/original.gif</original>

<max200>/images/mix_covers/max200.gif</max200>


<max133w>/images/mix_covers/max133w.gif</max133w>

</cover_urls>

<id>1002</id>


<user>

<slug>thrillist</slug>

<id>2455</id>

<avatar-urls>

<sq56>/images/avatars/sq56.jpg</sq56>



<max200>/images/avatars/max200.jpg</max200>

</avatar-urls>

<login>Thrillist</login>


</user>

<tag-list-cache>alternative rock, pop, unknown genre</tag-

list-cache>


<description>LA's best local bands, picked by Spaceland guru Mitchell Frank in anticipation of Sunset Junction.</description>

<path>/thrillist/thrillists-mitchell-frank-sunset-junction-mix</path>


<first-published-at>2008-08-21T17:13:44Z</first-published-at>

</mix>



</response>

Playback

Play Tokens are used to control access and playback of mixes and tracks. Rules, such as randomized tracks after the first listen of a mix, are applied accordingly.

Play tokens are scoped around a single user for unlimited mix playback. To create a new play token call:

curl http://8tracks.com/sets/new.xml

<response>


<logged-in type="boolean">false</logged-in>



<play-token>726890873</play-token>

</response>

With a play token you can select a mix for playback. To select the mix you'll need the mix id available from the Discovery API.

curl http://8tracks.com/sets/460486803/play.xml?mix_id=2000

<response>


<set>

<at-beginning>false</at-beginning>

<at-end>false</at-end>

<skip-allowed>true</skip-allowed>

<track>

<release-name>Justified</release-name>

<faved-by-current-user>false</faved-by-current-user>

<year nil="true"></year>

<name>Rock Your Body</name>

<play-duration>0</play-duration>

<performer>Justin Timberlake</performer>

<id>16952</id>

<url>http://8tracks.s3.amazonaws.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e637935be86c382.mp3</url>

</track>

</set>




</response>

at-beginning: true if you are at the first track in the mix

at-end: true if you are at the last track in the mix

skip-allowed: true if you can skip at this point or if the maximum number of skips has been reachedThis field is only meaningful after you have first called skip.xml http://8tracks.s3.amazonaws.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e637935be86c382.mp3http://8tracks.s3.amazonaws.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e637935be86c382.mp3http://8tracks.s3.amazonawsTtt.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e637935be86c382.mp3

After the track has finished playing simply call 'next':

curl http://8tracks.com/sets/460486803/next.xml?mix_id=2000

OR the user selects "skip track", then call 'skip':

curl http://8tracks.com/sets/460486803/skip.xml?mix_id=2000

If skipping is not allowed you will get the following response:

curl http://8tracks.com/sets/460486803/skip.xml?mix_id=2000

<response>


<logged-in type="boolean">false</logged-in>

<status>403 Forbidden</status>

<notices>

<notice>Apologies for the inconvenience, but our music license requires us to limit the number of tracks you may skip each hour.</notice>

</notices>

</response>

In your code you must distinguish between the end of a song and the user skipping to the next song.If you call skip.xml (or skip.json) you will get the next song in the mix if 'skip' has not been called three times on that mixduring the current 60 minute timeframe. If 'skip' has been called more than three times you will get theresponse header listed above.

Each time you call skip, you should check the status field of the response or check the code in theresponse-headers before you attempt to parse the results.

User Data

View user info:

curl http://8tracks.com/users/1.xmlor curl http://8tracks.com/users/remi.xml

<response>




<user>

<slug>remi</slug>

<next-mix-prefs>ask</next-mix-prefs>

<id>1</id>

<popup-prefs>ask</popup-prefs>

<avatar-urls>





</avatar-urls>

<login>remi</login>


</user>


</response>

List mixes made by a user:

curl http://8tracks.com/users/2/mixes.xmlor curl http://8tracks.com/users/dp/mixes.xml

<response>



<page>1</page>

<per-page>10</per-page>


<total-entries>38</total-entries>

<mixes>

<mix>

<slug>the-albion-chill</slug>

<name>The Albion Chill</name>


<cover_urls>



<original>http://cf2.8tracks.us/mix_covers/000/111/610/98445.original.jpg</original>

<max200>http://cf2.8tracks.us/mix_covers/000/111/610/98445.max200.jpg</max200>


<max133w>http://cf2.8tracks.us/mix_covers/000/111/610/98445.max133w.jpg</max133w>

</cover_urls>

<id>111610</id>


<user>

<slug>dp</slug>

<id>2</id>

<avatar-urls>





</avatar-urls>

<login>dp</login>


</user>

<tag-list-cache>trip hop, chill, electronic</tag-list-cache>


<description>Twelve kickback tracks from 24 months (2000-01) on Albion Street in SF, including music by Air, DJ Shadow and Stardust.

Early evenings preparing for a night out.</description>

<path>/dp/the-albion-chill</path>


<first-published-at>2010-04-28T09:41:21Z</first-published-at>

</mix>

...

</mixes>

<next-page>2</next-page>


</response>

You can use the "view" parameter to list mixes in a user's Mix Feed:

curl http://8tracks.com/users/2/mixes.xml?view=mix_feedor curl http://8tracks.com/users/dp/mixes.xml?view=mix_feed

List liked mixes by a user

curl http://8tracks.com/users/2/mixes.xml?view=likedor curl http://8tracks.com/users/dp/mixes.xml?view=liked

You can even request different groups in a single request. Mixes by user + Liked mixes for user:

curl http://8tracks.com/users/2/mixes.xml?view=mix_feed+liked

or curl http://8tracks.com/users/2/mixes.xml?view=mix_feed+liked

User Actions (authenticated)

There are 3 kinds of actions that users can take towards mixes, tracks and other users:

- for a mix: like / unlike / toggle_like

- for a track: fav / unfav / toggle_fav

- for a user: follow / unfollow / toggle_follow

For these actions, you must be logged in.

Toggling Mix Like

curl -u remi:good --request POST -d '' http://8tracks.com/mixes/14/toggle_like.json

<response>





<mix>

<id>14</id>

<liked-by-current-user>true</liked-by-current-user>

</mix>

</response>

liked_by_current_user: lets you know if the current user likes this mix. This is returned everywhere in the API when you get a mix.

Liking a Mix

curl -u remi:good --request POST -d '' http://8tracks.com/mixes/14/like.xml

<response>





<mix>

<id>14</id>

<liked-by-current-user>true</liked-by-current-user>

</mix>

</response>

Un-liking a Mix

curl -u remi:good --request POST -d '' http://8tracks.com/mixes/14/unlike.xml

<response>





<mix>

<id>14</id>


</mix>

</response>

Toggling Track Fav

curl -u remi:good --request POST -d '' http://8tracks.com/tracks/23/toggle_fav.xml

<response>





<track>

<id>23</id>

<faved-by-current-user>true</faved-by-current-user>

</track>

</response>

faved_by_current_user: lets you know if the current user faved this track. This is returned everywhere in the API when you get a track.

Favoriting a Track

curl -u remi:good --request POST -d '' http://8tracks.com/tracks/23/fav.xml

<response>





<track>

<id>23</id>

<faved-by-current-user>true</faved-by-current-user>

</track>

</response>

Un-favoriting a Track

curl -u remi:good --request POST -d '' http://8tracks.com/tracks/23/unfav.xml

<response>





<track>

<id>23</id>

<faved-by-current-user>false</faved-by-current-user>

</track>

</response>

Toggling User Follow

curl -u remi:good --request POST -d '' http://8tracks.com/users/1/toggle_follow.xml

<response>





<user>

<id>1</id>

<followed-by-current-user>true</followed-by-current-user>

</user>

</response>

followed_by_current_user: lets you know if the current user follows this user. This is returned everywhere in the API when you get a user.

Following a User

curl -u remi:good --request POST -d '' http://8tracks.com/users/1/follow.xml

<response>





<user>

<id>1</id>

<followed-by-current-user>true</followed-by-current-user>

</user>

</response>

Un-following a User

curl -u remi:good --request POST -d '' http://8tracks.com/users/1/unfollow.xml

<response>





<user>

<id>1</id>


</user>

</response>

Official 8tracks API v2

Documents

Transcript of Official 8tracks API v2