API Documentation (version 2.1)
— Deprecation notice —
This page is superseded by new documentation for API version 3.0. Please use the new version whenever possible. This document describes the API version 2.1 and will be maintained for legacy purposes.
This developer API offers a pretty typical RESTful interface and all calls are available in 3 formats:
JSON, XML, and JSONP.
You can pick your format by appending what you need at the end of the URL or by passing a parameter called format.
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:
- 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: a string that lists errors that occurred during this request.
- notices: a string of what happened during the request such as 'logged in successfully'
- logged-in: indicates if you are currently logged in
And when you're being returned 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.
If you don't have one yet, go get a Developer API key.
Don't lose it because you'll need to pass this key on every request.
You can pass your API key in 2 ways: as a parameter or as a custom HTTP header:
Step 1: Verify credentials
Before you can call our API with user credentials, you must first verify that you have the correct login/password.
You can use HTTPS/SSL in order to avoid passing user credentials in clear.
We currently support 2 kinds of authentication:
- User token Authentication (the preferred way)
- Basic HTTP Authentication
Step 2: User token Authentication
This is the preferred authentication method. Once you verified the user credentials, you need to save the "user-token" value passed in the response. You can then use this token as a parameter or as a header to login the user on all subsequent requests:
(Alternate) Step 2: Basic Authentication
Once you verify user credentials, you can use Basic Authentication for any call requiring authentication. If you use incorrect credentials:
This is what you get when you use correct credentials:
Signing up Users
Creating a user account is similar to logging in. It will return the same user object and user authentication token.
Status returned can be 201 if successful or 422 is there's a validation error.
The simplest call possible is to get the latest 10 mixes:
To view the next page of results specifiy the page number:
NOTE: The page parameter works for all paginated API calls.
To search or filter the results append the criteria:
Or to list mixes by tag, use the tag parameter:
You can also order results in 4 ways:
And you can pass multiple tags but don't forget to escape your URL parameters:
Finding recent mixes tagged "chill" and "hip hop":
And change the number of entries per page:
For information on a single mix:
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:
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.
- at-beginning: true if you are at the first track in the mix
- at-last-track: true if you reached the final track in the mix.
- at-end: true if you are past the final track.
- 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
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.
DON'T FORGET: Reporting the song
In order to be legal and pay royalties properly, 8tracks must report every performance of every song played to SoundExchange. A "performance" is counted when the 30 second mark of a song is reached. So at 30 seconds, you must call the following:
More on playing mixes
Get a similar mixWhen playback reaches the end of the mix, it's nice for users to redirect them to another similar mix so music keeps playing.
Get the next mix in the setGetting a similar mix is nice but to keep the experience as consistent as possible with the website, it's even better to keep users in context. For instance, if a user is listening to his/her "liked mixes" and is done with the first mix in the list, we want to redirect him/her to the 2nd mix on that list.
We call a list of mixes, a "mix set" and every "mix set" has a unique id. You need to do 2 things to get this working:
- Grab the "id" value returned along any list of mixes (check out the Find mixes section to view the response)
- Pass this value as a parameter named "mix_set_id"
Get the list of tracks already playedWhen loading a mix, the user may have already started listening to it before so it's best to preload the tracks already listened.
Hide NSFW mixesIf you know 8tracks, you know that some mix covers are pretty hot but unfortunately inappropriate on some platforms. We let our users report these mixes as NSFW (Not Safe For Work).
Logged in users have the ability to hide/show NSFW mixes directly in their settings so you don't need to do anything special for them.
If you want to hide NSFW mixes everywhere though, you have 2 options:
- you can add the "safe_browse" parameter to any query returning mixes, for instance: http://8tracks.com/mixes.xml?safe_browse=1
- or, you can look at the "nsfw" value on each mix returned and hide its cover when nsfw=true.
UsersView user info: List mixes made by a user: You can use the "view" parameter to list mixes in a user's Mix Feed: List liked mixes by a user
ReviewsGetting the paginated reviews (aka comments) from a mix: Getting the paginated reviews (aka comments) posted by a user: Posting a review on a mix:
Tags are the preferred way for browsing 8tracks mixes.
Browse and search tagsGet the top tags:
Search tags (very cool for autocompleting):
Like Mixes, Tracks or Users
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
- 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
Un-liking a Mix
Toggling Track Fav
- 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
Un-favoriting a Track
Toggling User Follow
- 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.