Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
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. 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> <logged-in>false</logged-in> <status>422 Unprocessable Entity</status> <errors>
Good Password
curl --request POST -d "login=remi&password=good" http://8tracks.com/sessions.xml <response> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <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> <sq72>http://cf1.8tracks.us/avatars/000/000/001/12363.sq72.jpg</sq72>
<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>
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> <logged-in>false</logged-in> <status>200 OK</status> <page>1</page> <per-page>8</per-page> <errors nil="true"></errors> <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</sq5
<sq100>http://cf3.8tracks.us/mix_covers/000/125/363/79524.sq100.jpg</s
<original>http://cf3.8tracks.us/mix_covers/000/125/363/79524.original.jpg</or
<max200>http://cf3.8tracks.us/mix_covers/000/125/363/79524.max200.jpg<
<sq133>http://cf3.8tracks.us/mix_covers/000/125/363/79524.sq133.jpg</s
<max133w>http://cf3.8tracks.us/mix_covers/000/125/363/79524.max133w.jpg</max1 </cover_urls>
<sq56>http://cf3.8tracks.us/avatars/000/072/787/73540.sq56.jpg</sq56
<sq72>http://cf3.8tracks.us/avatars/000/072/787/73540.sq72.jpg</sq72
<sq100>http://cf3.8tracks.us/avatars/000/072/787/73540.sq100.jpg</sq
<max200>http://cf3.8tracks.us/avatars/000/072/787/73540.max200.jpg</ </avatar-urls> <login>violentlyoppossed</login> <followed-by-current-user>false</followed-by-current-user> </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-allliving</path> <restful-url>http://8tracks.com/mixes/125363</restful-url> <first-published-at>2010-06-12T22:22:28Z</first-published-at> </mix> ...
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?per_page=20
For information on a single mix:
curl http://8tracks.com/mixes/1002.xml <response> <logged-in>false</logged-in> <status>200 OK</status> <mix> <slug>thrillists-mitchell-frank-sunset-junctionmix</slug> <name>Thrillist's Mitchell Frank Sunset Junction Mix</name>
<published>true</published> <cover_urls> <sq56>/images/mix_covers/sq56.gif</sq56> <sq100>/images/mix_covers/sq100.gif</sq100> <original>/images/mix_covers/original.gif</original> <max200>/images/mix_covers/max200.gif</max200> <sq133>/images/mix_covers/sq133.gif</sq133> <max133w>/images/mix_covers/max133w.gif</max133w> </cover_urls> <id>1002</id> <liked-by-current-user>false</liked-by-current-user> <user> <slug>thrillist</slug> <id>2455</id> <avatar-urls> <sq56>/images/avatars/sq56.jpg</sq56> <sq72>/images/avatars/sq72.jpg</sq72> <sq100>/images/avatars/sq100.jpg</sq100> <max200>/images/avatars/max200.jpg</max200> </avatar-urls> <login>Thrillist</login> <followed-by-current-user>false</followed-by-currentuser> </user> <tag-list-cache>alternative rock, pop, unknown
genre</tag-list-cache> <plays-count>418</plays-count> <description>LA's best local bands, picked by Spaceland guru Mitchell Frank in anticipation of Sunset Junction.</description> <path>/thrillist/thrillists-mitchell-frank-sunsetjunction-mix</path> <restful-url>http://8tracks.com/mixes/1002</restfulurl> <first-published-at>2008-08-21T17:13:44Z</firstpublished-at> </mix> <errors nil="true"></errors> <notices nil="true"></notices> </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/460486803/play.xml?mix_id=2000 <response> <status>200 OK</status> <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_8 </track>
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 reached This field is only meaningful after you have first called skip.xml http://8tracks.s3.amazonaws.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e637935be86c 382.mp3http://8tracks.s3.amazonaws.com/tf/000/016/952/Rock_Your_Body_mp3_887f6e6379 35be86c382.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> <notices nil="true"></notices> <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 mix during the current 60 minute timeframe. If 'skip' has been called more than three times you will get the response header listed above. Each time you call skip, you should check the status field of the response or check the code in the response-headers before you attempt to parse the results.
User Data
View user info:
curl http://8tracks.com/users/1.xml or curl http://8tracks.com/users/remi.xml <response> <logged-in>false</logged-in> <status>200 OK</status> <errors nil="true"></errors> <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>
<sq72>http://cf1.8tracks.us/avatars/000/000/001/12363.sq72.jpg</sq72>
curl http://8tracks.com/users/2/mixes.xml or curl http://8tracks.com/users/dp/mixes.xml <response> <logged-in>false</logged-in> <status>200 OK</status> <page>1</page> <per-page>10</per-page> <errors nil="true"></errors> <total-entries>38</total-entries> <mixes> <mix> <slug>the-albion-chill</slug>
<sq56>http://cf2.8tracks.us/mix_covers/000/111/610/98445.sq56.jpg</sq5
<sq100>http://cf2.8tracks.us/mix_covers/000/111/610/98445.sq100.jpg</s
<original>http://cf2.8tracks.us/mix_covers/000/111/610/98445.original.jpg</or
<max200>http://cf2.8tracks.us/mix_covers/000/111/610/98445.max200.jpg<
<sq133>http://cf2.8tracks.us/mix_covers/000/111/610/98445.sq133.jpg</s
<sq56>http://cf2.8tracks.us/avatars/000/000/002/83251.sq56.jpg</sq56
<sq72>http://cf2.8tracks.us/avatars/000/000/002/83251.sq72.jpg</sq72
<sq100>http://cf2.8tracks.us/avatars/000/000/002/83251.sq100.jpg</sq
<description>Twelve kickback tracks from 24 months (2000-01) on Albion S SF, including music by Air, DJ Shadow and Stardust. Early evenings preparing for a night out.</description> <path>/dp/the-albion-chill</path> <restful-url>http://8tracks.com/mixes/111610</restful-url> <first-published-at>2010-04-28T09:41:21Z</first-published-at> </mix> ... </mixes> <next-page>2</next-page> <notices nil="true"></notices> </response>
You can use the "view" parameter to list mixes in a user's Mix Feed:
curl -u remi:good --request POST -d '' http://8tracks.com/mixes/14/toggle_like.json <response> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <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> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <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> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices>
curl -u remi:good --request POST -d '' http://8tracks.com/tracks/23/toggle_fav.xml <response> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <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
<response> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <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> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <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> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <user> <id>1</id> <followed-by-current-user>true</followed-by-currentuser> </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> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <user> <id>1</id> <followed-by-current-user>true</followed-by-current-
Un-following a User
curl -u remi:good --request POST -d '' http://8tracks.com/users/1/unfollow.xml <response> <logged-in>true</logged-in> <status>200 OK</status> <errors nil="true"></errors> <notices nil="true"></notices> <user> <id>1</id> <followed-by-current-user>false</followed-by-currentuser> </user> </response>