API / Smart IDs

Smart IDs are permanent, unique identifiers for MixSets that are used to access them through the API. They encode useful information about the set and determine the kind of results you will get back. The simplest way to think of them is as serialized versions of the parameters you would use pull mixes from the API in a query string.

The master format for Smart IDs is as follows: 

 smart_type(:id|:slug)(:sort)(:safe)

Once you have a smart_id, you can access all of the data for that mix set at this endpoint:

http://8tracks.com/mix_sets/smart_id.format?include=includes

An example call might look like this:

http://8tracks.com/mix_sets/all:popular.json?include=mixes[likes_count],pagination

(See the include documentation for the available fields for each object.)



Smart types

The following smart_types are available to everyone:

  • all — The unfiltered set of all mixes.
  • tags — Mixes filtered by a tag or multiple tags. This is the most common way to browse.
  • artist — Mixes filtered by artist match within the tracklist.
  • keyword — Fulltext search results for a string, ordered by relevance.
  • dj — The mixes published by a particular user, in reverse-chronological order.
  • liked — The mixes published by a particular user, in reverse-chronological order.
  • similar — Mixes with high similarity to a given mix, with help from The Echo Nest.

These smart_types are available for logged-in users only:

  • feed — Mixes published by users you follow, in reverse chronological order.
  • social_feed — Mixes published and/or liked by users you follow, representing that user's "Feed." Order is determined by recent activity.
  • listened — Mixes you've listened to, in reverse chronological order.
  • recommended — Mixes recommended for you based on tracks your activity, with help from The Echo Nest.
  • liked and dj may also be used without a user_id to access one's own liked and published mixes while logged in.


Numerical IDs

When a mix set is identified by a particular object, such as a User, Collection, or an individual Mix, then the corresponding numerical ID is appended to the smart ID to specify it.

For example, the user-specific sets dj:1 & recommended:2 would specify the mixes published by the user with ID=1, and the mixes recommended for the user with ID=2. The following smart types take the user_id as an identifier:

  • dj:user_id
  • feed:user_id
  • social_feed:user_id
  • liked:user_id
  • listen_later:user_id
  • recommended:user_id

Collections are also identified by the user's a numerical ID. They are the simplest kind of mix set, in that they're just a hand-picked list of mixes with no other options. They may be accessed by combining the the user's numerical ID and the slug attribute of the collection, like so: collection:123:my-collection.

Similar mixes are identified by the numerical ID of the mix that seeds the list, like so: similar:123



Slugs

When a mix set is identified by a particular string, such as a keyword search, that string is encoded and used as the identifier within the smart ID, e.g. keyword:instrumental_hip_hop. This method is applicable for the following smart_types: Tags, Artist, Keyword.

The encoded version of these strings are called url params, meaning they are UTF-8, url-safe strings which have additional substitutions to make them safe to use within the URL path, rather than just in the query string. These are the additional substitutions:

  • Underscores (_) are replaced with double underscores (__)
  • Spaces ( ) are replaced with underscores (_)
  • Forward slashes are replaced with backslashes (\)
  • Periods or dots (.) are replaced with carets (^)

Note that these substitutions should take place before URL-encoding.

Here is a ruby (rails) helper that will encode a string as url param (and decode it again).

URL_PARAM_SUBSTITUTIONS = [
  [ '_[^_]', '__' ]
  [ ' ', '_'  ],
  [ '/', '\\' ],
  [ '.', '^'  ]
]

def to_url_param(initial_param)
  # clone to avoid overwriting instance values passed as arguments
  param = initial_param.clone
  param.strip!
  
  URL_PARAM_SUBSTITUTIONS.each do |decoded, encoded|
    param = param.gsub(decoded, encoded)
  end
  
  Rack::Utils.escape(param)
end

Here is a javascript function that will encode a string as a url param

function toUrlParam(param) {
  if (_.isString(param)) {
    return encodeURIComponent(param.replace(/_/g, '__').replace(/\s/g, '_').replace(/\//g, '\\').replace(/\./g, '^'));
  }
};

Both of these functions return URL-encoded strings, but for readability our API returns non-URL-encoded versions.

Also note that for Tags mix sets selecting multiple tags, each tag should be escaped separately and the resulting list joined with the + symbol, like so: tags:chill+indie_rock+singer\songwriter. We also sort the tags alphabetically to make the smart IDs unique.



Sorting

Some mix sets have alternate sorting methods available. These are all, tags, and artist. The available sorts are hot, recent, and popular. These correspond to the names Trending, Newest, and Popular on the official 8tracks apps. By default these mix sets will return the hot sort order, but to use another, just append it to the smart ID like so: tags:pop:recent, or all:popular.

Note: on the website, we also show Liked and Feed as options in the sort dropdown for tag searches, but these are actually using tag filters on the liked and feed mix sets, not a different "sort" order on the tags mix set.



Safe browse

Any mix set may be viewed in "Safe browse" mode by appending :safe to the end of the smart id. This will filter out mixes that have been flagged as NSFW by the DJ, an admin, or users.

Examples

There follows a list of example smart_ids you may find helpful:

  • all
  • all:recent
  • all:popular
  • tags:singer\songwriter
  • tags:hip_hop:popular
  • tags:hip_hop+old-school
  • tags:west_coast+g-funk:recent
  • artist:Kanye_West
  • artist:N^W^A:safe
  • dj:2
  • feed:2:safe
  • social_feed:2
  • listened:2
  • listen_later:2
  • recommended:2
  • collection:645:favorite-artwork
  • similar:2206409


Written by Matthew Cieplak, 8tracks Senior Developer
Updated August 16, 2013


 
Quantcast