Premium Playlisting

Employing The Echo Nest’s most advanced playlisting capabilities, Premium Playlisting leverages our deep understanding of music culturally and acoustically, as well as listener preferences to deliver incredibly unique and personalized music experiences. In addition to generating playlists incorporating an end user’s personal preferences and real-time feedback, playlists can be customized or ‘tuned’ by a customer’s editorial team or by the end user using a variety of cultural and acoustic attributes. Playlist results may be constrained to the customer’s complete music catalog, an individual Taste Profile, or custom-curated Station Profiles.

Premium Playlisting API Methods:

  • Static Playlist API - A simple “query-response” API method that generates a playlist of up to 100 tracks based on 1-5 artists, * 1-5 songs, 1-5 genres, or a single Taste Profile. The static playlist API method is further described at: http://developer.echonest.com/docs/v4/premium.html#static.
  • Dynamic Playlist APIs - A suite of APIs designed to deliver an interactive, personalized radio experience that incorporates real-time feedback and steering from the end user. Each dynamic playlist session creates a new session ID, which maintains rules for playlist generation, listening activity (plays, skips) and user feedback (bans, favorites, ratings) to ensure continuity and an increasingly personalized playlist experience. Dynamic Playlist API methods ar further described at: http://developer.echonest.com/docs/v4/premium.html#dynamic-create
  • Taste Profile APIs - Enables customers to maintain a collection of artists and/or songs associated with a specific end user, as well as their activity and preferences around that music. Dynamic playlist session activity (plays, skips) and feedback (bans, favorites, ratings) can be recorded to a Taste Profile. Unlike session IDs, which expire after 24 hours of inactivity, Taste Profiles allow listening activity and feedback to inform future playlist sessions. Taste Profile API methods are further described at: http://developer.echonest.com/docs/v4/catalog.html.

Playlist types available with Premium Playlisting include the following:

  • artist-radio - Plays songs from the given artist(s) and similar artists.
  • song-radio - Plays songs similar to the given song(s).
  • genre-radio - Plays songs from artists relevant to the given genre.
  • artist - Plays songs from only the given artist(s).
  • catalog - Plays songs listed in the given Taste Profile.
  • catalog-radio - Plays songs listed in the given Taste Profile, as well as similar artists and songs outside of the Taste Profile.

Playlist controls available with Premium Playlisting include the following:

  • limited_interactivity - Returns a playlist based on limited interactivity rules.
  • genre_preset - fine grained control over the genre radio. See below.
  • Song Type - Include or exclude songs categorized as christmas, acoustic, electric, live and studio.
  • Variety - Controls the variety of artists that appear in a playlist. Values range from 0-1 and higher values will allow for more variety in the artists.
  • Distribution - Controls the distribution of similar artists in the playlist. A ‘focused’ distribution yields a playlist of songs that are tightly clustered around the seeds, whereas a ‘wandering’ distribution yields a playlist from a broader range of artists.
  • Adventurousness - Controls how much music in the playlist is known or unknown to the user based on a given Taste Profile. Values range from 0-1 and higher values indicate a higher level of adventurousness. (catalog and catalog-radio playlists type only)

Playlist tuning attributes available with Premium Playlisting include the following:

  • Tempo - a numerical value representing the beats per minute (BPM) of a song.
  • Duration - a numerical value representing the length of a song in seconds.
  • Danceability - a score between 0-1 of how easy it may be to dance to a song.
  • Loudness - a score between 0-1 of the overall volume of a song.
  • Energy - a score between 0-1 of the overall energy of a song.
  • Artist Familiarity - a score between 0-1 of how familiar an average person is with artist.
  • Artist Hotttnesss - a score between 0-1 indicating recent online activity for an artist.
  • Song Hotttnesss - a score between 0-1 indicating recent online activity for a song.

static

Returns a static playlist. A static playlist is generated once from an initial set of parameters, and returned as an ordered list of songs. A simple “query-response” API method that generates a playlist of up to 100 tracks based on 1-5 artists, 1-5 songs, 1-5 genres, or a single Taste Profile. Some properties of a static playlist:

  • Songs are never repeated
  • Artists may be repeated

A number of different algorithms can be used to select songs for the playlist. These are specified with the type parameter.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY your API key
format no no json, xml, jsonp the format of the returned playlist
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
type no no artist, artist-radio, song-radio, catalog, catalog-radio, genre-radio the type of the playlist to be generated. See below for details on each of the types
artist_pick (deprecated, use song_selection) no no song_hotttnesss-desc tempo, duration, loudness, mode, key The artist_pick parameter is used to determine how songs are picked for each artist in artist-type playlists. If the asc or desc suffix is ommitted, artist_pick defaults to descending.
song_selection no no PARAMETER-SUFFIX where PARAMETER can be one of song_hotttnesss, song_discovery, song_currency, acousticness, tempo, energy, danceability, liveness, speechiness, duration, loudness, valence, and SUFFIX is one of '-top' or '-bottom'. Default is song_hotttnesss-top This parameter is used to determine how songs are selected from each artist in artist and genre type playlists. For instance, if song_selection is 'song_hotttnesss-top' then the top hotttest songs for each candidate artist are added to the song pool used to build the playlist. Likewise if the parameter is 'tempo-bottom', the slowest songs are selected from each candidate artist for the song pool.
variety no no 0 - 1 (default = 0.5) the maximum variety of artists to be represented in the playlist. A higher number will allow for more variety in the artists.
distribution no no focused, wandering Controls the distribution of artists in the playlist. A focused distribution yields a playlist of songs that are tightly clustered around the seeds, whereas a wandering distribution yields a playlist from a broader range of artists.
adventurousness no no 0 - 1 (default = 0.2) Controls the trade between known music and unknown music. A value of 0 means no adventurousness, only known and preferred music will be played. A value of 1 means high adventurousness, mostly unknown music will be played. A value of auto indicates that the adventurousness should be automatically determined based upon the taste profile of the user. This parameter only applies to catalog and catalog-radio type playlists.
artist_id no yes (no more than 5 total total artist_id, artist, track_id, and song_id parameters) ARH6W4X1187B99274F, 7digital-US:artist:304 ID(s) of seed artist(s) for the playlist. Echo Nest or Rosetta IDs
artist no yes (no more than 5 total total artist_id, artist, track_id, and song_id parameters) Weezer, the+beatles Name(s) of seed artist(s) for the playlist
seed_catalog no no CAKSMUX1321A708AA4 ID of seed catalog for the playlist
song_id no yes (no more than 5 total total artist_id, artist, track_id, and song_id parameters) SOCZMFK12AC468668F ID(s) of seed song(s) for the playlist (used by some types). Echo Nest or Rosetta IDs
track_id no yes (no more than 5 total total artist_id, artist, track_id, and song_id parameters) TRTLKZV12E5AC92E11 ID(s) of seed tracks(s) for the playlist (used by playlist types that accept songs as seeds). Echo Nest or Rosetta IDs
genre no yes (up to 5) jazz, metal a musical genre such as rock, jazz, or dance pop. See the artist method list_genres for details on what genres are currently available, only allowed for genre-radio playlist types and required for genre-radio playlist types.
genre_preset no no core-best, core-shuffled, in_rotation-best, in_rotation-shuffled, emerging-best, emerging-shuffled provides control over the type of genre radio to be generated (see the genre_preset section below for details).
results no no 0 - 100 (default = 15) the desired number of songs in the playlist
max_tempo no no 0.0 < tempo < 500.0 (BPM) the maximum tempo for any included songs
min_tempo no no 0.0 < tempo < 500.0 (BPM) the minimum tempo for any included songs
target_tempo no no 0.0 < tempo < 500.0 (BPM) the target tempo for any included songs
max_duration no no 0.0 < duration < 3600.0 (seconds) the maximum duration of any song on the playlist
min_duration no no 0.0 < duration < 3600.0 (seconds) the minimum duration of any song on the playlist
target_duration no no 0.0 < duration < 3600.0 (seconds) the target duration of any song on the playlist
max_loudness no no -100.0 < loudness < 100.0 (dB) the maximum loudness of any song on the playlist
min_loudness no no -100.0 < loudness < 100.0 (dB) the minimum loudness of any song on the playlist
target_loudness no no -100.0 < loudness < 100.0 (dB) the target loudness of any song on the playlist
max_danceability no no 0.0 < danceability < 1.0 the maximum danceability of any song
min_danceability no no 0.0 < danceability < 1.0 the minimum danceability of any song
target_danceability no no 0.0 < danceability < 1.0 the target danceability of any song
max_energy no no 0.0 < energy < 1.0 the maximum energy of any song
min_energy no no 0.0 < energy < 1.0 the minimum energy of any song
target_energy no no 0.0 < energy < 1.0 the target energy of any song
max_liveness no no 0.0 < liveness < 1.0 the maximum liveness of any song
min_liveness no no 0.0 < liveness < 1.0 the minimum liveness of any song
target_liveness no no 0.0 < liveness < 1.0 the target liveness of any song
max_speechiness no no 0.0 < speechiness < 1.0 the maximum speechiness of any song
min_speechiness no no 0.0 < speechiness < 1.0 the minimum speechiness of any song
target_speechiness no no 0.0 < speechiness < 1.0 the target speechiness of any song
max_acousticness no no 0.0 < acousticness < 1.0 the maximum acousticness of any song. This is a beta feature.
min_acousticness no no 0.0 < acousticness < 1.0 the minimum acousticness of any song. This is a beta feature.
target_acousticness no no 0.0 < acousticness < 1.0 the target acousticness of any song. This is a beta feature.
artist_max_familiarity no no 0.0 < familiarity < 1.0 the maximum artist familiarity for songs in the playlist
artist_min_familiarity no no 0.0 < familiarity < 1.0 the minimum artist familiarity for songs in the playlist
target_artist_familiarity no no 0.0 < familiarity < 1.0 the target artist familiarity for songs in the playlist
artist_max_hotttnesss no no 0.0 < hotttnesss < 1.0 the maximum artist hotttness for songs in the playlist
artist_min_hotttnesss no no 0.0 < hotttnesss < 1.0 the minimum artist hotttnesss for songs in the playlist
target_artist_hotttnesss no no 0.0 < hotttnesss < 1.0 the target artist hotttnesss for songs in the playlist
song_type no yes christmas, live, studio, acoustic, electric. controls the type of songs returned. Supported song_types are: 'christmas', 'live', 'studio'. A song type can optionally be followed by ':' and a state, where the state can be one of 'true', 'false', 'seed' or 'any'. If no state is given, the desired state is assumed to be 'true'. For a state of 'seed', songs in the playlist will match the type of the song seeds if they all agree.
artist_start_year_before no no 1970, 2011, present Matches artists that have an earliest start year before the given value
artist_start_year_after no no 1970, 2011, present Matches artists that have an earliest start year after the given value
artist_end_year_before no no 1970, 2011, present Matches artists that have a latest end year before the given value
artist_end_year_after no no 1970, 2011, present Matches artists that have a latest end year after the given value
song_max_hotttnesss no no 0.0 < hotttnesss < 1.0 the maximum hotttnesss for songs in the playlist
song_min_hotttnesss no no 0.0 < hotttnesss < 1.0 the minimum hotttnesss for songs in the playlist
target_song_hotttnesss no no 0.0 < hotttnesss < 1.0 the target hotttnesss for songs in the playlist
bucket no yes audio_summary, artist_discovery, artist_discovery_rank, artist_familiarity, artist_familiarity_rank, artist_hotttnesss, artist_hotttnesss_rank, artist_location, song_currency, song_currency_rank, song_hotttnesss, song_hotttnesss_rank, song_type, tracks, id:Rosetta-space indicates what data should be returned in the playlist (for json and xml types only)
sort no no tempo-asc, duration-asc, loudness-asc, speechiness-asc, acousticness-asc, liveness-asc, artist_familiarity-asc, artist_hotttnesss-asc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc, song_hotttnesss-asc, latitude-asc, longitude-asc, mode-asc, key-asc, tempo-desc, duration-desc, loudness-desc, liveness-desc, speechiness-desc, acousticness-desc, artist_familiarity-desc, artist_hotttnesss-desc, song_hotttnesss-desc, latitude-desc, longitude-desc, mode-desc, key-desc, energy-asc, energy-desc, danceability-asc, danceability-desc indicates how the songs should be ordered in the playlist
limit no no true, false if 'true', limit the results to any of the given idspaces or catalogs
dmca (deprecated) no no true, false If true, 'stylea' or 'styleb' the playlist delivered will meet the limited interactivity rules (see below). This parameter has been renamed to limited_interactivity.
limited_interactivity no no true, false, stylea, styleb If true, 'stylea' or 'styleb' the playlist delivered will meet the limited interactivity rules (see below).

Warning

If limit is set to anything but false, at least one idspace must also be provided in the bucket parameter.

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element.

limited interactivity: When the limited_interactivity parameter is set to true, the playlist will conform to the following rules:
  • no more than 2 songs in a row from the same album
  • no more than 3 songs from an album in a 3 hour period
  • no more than 3 different songs in a row by the same artist
  • no more than 4 songs by the same artist in a 3 hour period

If limited_interactivity is set to true, skipped songs are not considered to have been played for limited interactivity conformance purposes. If limited_interactivity is set to 'styleb', skipped songs are considered to have been played for limited interactivity purposes.

Playlist Types:
  • artist - plays songs for the given artists
  • artist-radio - plays songs for the given artists and similar artists
  • genre-radio - plays songs from artists matching the given genre
  • song-radio - plays songs similar to the song specified.
  • catalog - the playlist is personalized based upon the given seed catalog. Results are limited to items listed in the given catalog.
  • catalog-radio - the playlist is personalized based upon the given seed catalog. Results are limited to items listed in the given catalog and items that are similar to items in the given catalog.

Notes on Catalog and Catalog Radio Playlists: Catalog and Catalog Radio playlists are seeded with one seed Personal Catalog (aka Taste Profile) via the seed_catalog parameter. The seed_catalog can be an artist catalog, a song or general catalog. For a catalog playlist with artist catalog seed, a playlist is generated that is limited to songs by artists that are in the seed catalog. For a catalog playlist with song or general catalog seed, a playlist is generated that is limited to songs that are in the seed catalog. For a catalog radio playlist with an artist catalog seed, a playlist is generated that is limited to songs by artists that are in the seed catalog or songs by artists that are similar to artists that are in the seed catalog. For a catalog radio playlist with song or general catalog seed, a playlist is generated that is limited to songs that are in the seed catalog, songs by artists that are in the seed catalog and songs by artists that are similar to artists that are in the seed catalog. A seed catalog must contain at least one non-banned item.

The playlist may optionally be seeded with artists or songs as well (via the song_id, artist_id and/or artist parameters).

The selection of songs in the playlist is governed by the user's explicit preference for items (ratings, bans, favorites) and implicit preference (plays, skips) as well as the user's familiarity with items combined with the desired adventurousness for the playlist (as controlled by the 'adventurousness' parameter).

Song Type When generating a playlist, the song_type parameter can be used to restrict the playlist to songs that have a matching song_type state. Currently supported song types are:

  • christmas - songs that are appropriate to play during the Christmas holiday season
  • live - songs that were performed in front of an audience
  • studio - songs that were recorded in a studio
  • acoustic - songs that created mostly with acoustic technology. This is a beta feature.
  • electric - songs that created mostly with electric technology. This is a beta feature.

The song_type state can be one of the following values:

  • true - only return songs tagged as given type. If no state is given, 'true' is assumed.
  • false - only return songs not tagged as given type
  • seed - only return songs that match the song_type of the seed(s)
  • any - any songs can be returned, whether they match the type or not.

The syntax for setting a song type is as follows:

  • song_type=christmas - sets christmas song type to true
  • song_type=christmas:true - sets christmas song type to true
  • song_type=christmas:false - sets christmas song type to false
  • song_type=christmas:seed - sets christmas song type to match the seed
  • song_type=christmas:any - sets christmas song type to any

genre preset -A number of genre presets can be used with the genre-radio playlist type by setting the genre_preset parameter:

  • core-best - a optimal canonical collection of songs intended to introduce the genre to a novice listener
  • core-shuffled - a varying collection of songs intended to introduce the genre to a novice listener
  • in_rotation-best - the optimal collection of the most popular songs being played in the genre today
  • in_rotation-shuffled - a varying collection of the most popular songs being played in the genre today
  • emerging-best - the optimal collection of songs that are more popular than otherwise expected, and popular for niche audiences, but which are still unfamiliar to most listeners
  • emerging-shuffled - a varying collection of songs that are more popular than otherwise expected, and popular for niche audiences, but which are still unfamiliar to most listeners

Boosting: This method can take multiple seed artists or songs. You an give a seed more weight by boosting the item. A boost is an affinity for an argument that gives it more or less weight when making calculations based on the argument. In case arguments are not meant to be equally valued, the boost can help clarify where along a spectrum each argument falls. The boost is a floating point value, where 1 gives the normal weight. It is signified by appending a caret and weight to the argument. Prepending a seed with a '-' indicates that the item should be skipped.

Example boosting:

To give Radiohead a 2.75 boost:

id=ARH6W4X1187B99274F^2.75

To skip Weezer:

artist=-Weezer id=-AR633SY1187B9AC3B9

Example queries:

Plays tracks by Weezer and Radiohead:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&artist=Weezer&artist=radiohead&format=json&results=20&type=artist

Generates an artist radio playlist for Weezer:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&artist=Weezer&format=json&results=20&type=artist-radio

Generates a song radio playlist for Weezer's Pork And Beans:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&song_id=SOHTZUF12A8C13582B&format=json&results=20&type=song-radio

Generates an artist radio playlist for Weezer, but never play tracks by Muse

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&artist=Weezer&artist=-muse&format=json&results=20&type=artist-radio

Generates an artist radio playlist of Christmas songs by artists like Justin Bieber

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&artist=justin+bieber&format=json&results=20&type=artist-radio&song_type=christmas

Generates an genre radio playlist for dance pop:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&genre=dance+pop&format=json&results=20&type=genre-radio

Generates an genre radio playlist for jazz and blues:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&genre=jazz&genre=blues&format=json&results=20&type=genre-radio

Catalog Playlist Example

Play me music I like - Generates a genius-style playlist based upon a song catalog. No seed song is necessary. This is a one-click, ‘play me music I like' playlist:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4

Play me music I might like - Generates a more adventurous genius-style playlist based upon a song catalog. No seed song is necessary. This is a one-click, ‘play me music I like' playlist:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4&adventurousness=.8

Play me my old favorites - Generates a genius-style playlist of my most familiar songs in my song catalog. No seed song is necessary. This is a one-click, ‘play me music I like ' playlist:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4&adventurousness=0

Catalog Radio Playlists

Seeded Recommendation Radio - Generates a recommendation radio playlist, with a mix of my favorite music and new music, given an artist catalog and a seed artist. The artist doesn’t need to be in the catalog:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7&artist=weezer

Auto Recommendation Radio - Generates a recommendation playlist style playlist, based upon an artist catalog no seed artist is necessary:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7

Auto Recommendation - High Discovery - Generates a recommendation radio playlist, no seed artist is necessary, with high adventurousness:

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7&adventurousness=.9

Here is an example json response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "songs": [
            {
                "title": "Dreamin'",
                "artist_name": "Weezer",
                "artist_id": "AR633SY1187B9AC3B9",
                "id": "SOHBJKR1280EC909D4"
            },
            {
                "title": "This Is A Call'",
                "artist_name": "Foo Fighters",
                "artist_id": "AR6XPWV1187B9ADAEB",
                "id": "SOMPOYK1280ED5098B"
            },
            {
                "title": "Life in a glasshouse",
                "artist_name": "Radiohead",
                "artist_id": "ARH6W4X1187B99274F",
                "id": "SOAPCKQ127F3E1B7A8"
             }
        ]
     }
 }

Generates an artist playlist for weezer, with tracks from the 7Digital catalog

http://developer.echonest.com/api/v4/playlist/static?api_key=YOUR_API_KEY&artist=weezer&format=json&results=2&type=artist&bucket=id:7digital-US&bucket=tracks&limit=true

Here is an example json response:

{
    "response": {
        "songs": [
            {
                "artist_foreign_ids": [
                    {
                        "catalog": "7digital-US",
                        "foreign_id": "7digital-US:artist:7516"
                    }
                ],
                "artist_id": "AR633SY1187B9AC3B9",
                "artist_name": "Weezer",
                "id": "SOBSLVH12A8C131F38",
                "title": "Island In The Sun",
                "tracks": [
                    {
                        "catalog": "7digital-US",
                        "foreign_id": "7digital-US:track:20637990",
                        "foreign_release_id": "7digital-US:release:1914387",
                        "id": "TRTXLYU13A79B0B112",
                        "preview_url": "http://previews.7digital.com/clips/34/20637990.clip.mp3",
                        "release_image": "http://cdn.7static.com/static/img/sleeveart/00/019/143/0001914387_200.jpg"
                    }
                ]
            },
            {
                "artist_foreign_ids": [
                    {
                        "catalog": "7digital-US",
                        "foreign_id": "7digital-US:artist:94744"
                    }
                ],
                "artist_id": "ARQRQRA12131B4B5A8",
                "artist_name": "Cake",
                "id": "SOZXNWX131343927EA",
                "title": "Love You Madly",
                "tracks": [
                    {
                        "catalog": "7digital-US",
                        "foreign_id": "7digital-US:track:3156513",
                        "foreign_release_id": "7digital-US:release:282089",
                        "id": "TRDFWLB12E5ADFBA5F",
                        "preview_url": "http://previews.7digital.com/clips/34/3156513.clip.mp3",
                        "release_image": "http://cdn.7static.com/static/img/sleeveart/00/002/820/0000282089_200.jpg"
                    }
                ]
            }
        ],
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        }
    }
}

Experimental features:

Parameter Required? Multiple? Values Description
type no no artist-description the type of the playlist to be generated. If set to 'artist-description' plays songs from artists matching the given description, style or mood
description no yes alt-rock,-emo,harp^2 for playlists of type artist-description select artists that tend to match this given description
style no yes jazz, metal^2 for playlists of type artist-description select artists that tend to match this given style
mood no yes happy, sad^.5 for playlists of type artist-description select artists that tend to match this given mood
mode no no (minor, major) 0, 1 the mode of songs in the playlist
key no no (c, c-sharp, d, e-flat, e, f, f-sharp, g, a-flat, a, b-flat, b) 0 - 11 the key of songs in the playlist

dynamic

A suite of API methods designed to deliver an interactive, personalized radio experience that incorporates real-time feedback and steering from the end user. Each dynamic playlist session creates a new session ID, which maintains rules for playlist generation, listening activity (plays, skips) and user feedback (bans, favorites, ratings) to ensure continuity and an increasingly personalized playlist experience. The dynamic playlist will adapt the playlist session based upon a number of factors:

  • Played songs
  • Skipped songs
  • Rated songs/artists
  • Favorited songs/artists
  • Banned songs/artists
  • Playlist steering

dynamic/create

Creates a new dynamic playlist session. A dynamic playlist is created with an initial set of parameters that define rules for generating the playlist. A session identifier is returned that can be used with other dynamic methods to get new songs, provide feedback or to steer the playlist. Songs in the playlist can be fetched, one at a time, using the dynamic/next method. The playlist is dynamic in that it is adapted dynamically based on the listener's feedback and steering.

The dynamic/create method accepts the same set of parameters as the playlist/static method with the exception that the results parameter for the dynamic/create call is limited to return values of zero or one.

A dynamic session has a limited lifetime. It will expire after a certain period of inactivity (typically atleast 24 hours). If you wish to preserve the activity on a session, you can use a session_catalog to capture the user's plays, skips, bans and so on.

Additional parameters specific to dynamic/create are described here:

Parameter Required? Multiple? Values Description
session_catalog no yes (up to 5) CAKSMUX1321A708AA4 The IDs of catalogs that should be updated with session information (plays, skips, ratings,bans, favorites, etc). Multiple session catalogs can be listed and all will be updated with the same information. The session catalogs must have been previously created using the same API key as used in this call.
results no no 0 - 1 (default = 0) indicates the number of tracks that are to be returned from the initial create call.

Here's an example:

Creates a dynamic artist playlist for weezer:

http://developer.echonest.com/api/v4/playlist/dynamic/create?api_key=YOUR_API_KEY&artist=weezer&type=artist-radio

Returns:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "session_id": "7bf982d80ed8421c8c94dbd6de565e9d",
     }
 }

Creates a dynamic artist playlist for the artist 'Weezer' and returns the first song in the playlist in the rdio-US id space:

http://developer.echonest.com/api/v4/playlist/dynamic/create?api_key=YOUR_API_KEY&artist=weezer&type=artist-radio&results=1&bucket=id:rdio-US&bucket=tracks&limit=true

Returns:

{
    "response": {
        "status": {
            "version": "4.2",
             "code": 0,
             "message": "Success"
        },
    "session_id": "3eaf597c758541adab7b7bd527323f1e",
    "songs": [
        {
            "title": "My Name Is Jonas",
            "artist_name": "Weezer",
            "artist_foreign_ids": [
                {
                "catalog": "rdio-US",
                "foreign_id": "rdio-US:artist:r139688"
                }
            ],
            "tracks": [
                {
                    "foreign_release_id": "rdio-US:release:a234075",
                    "catalog": "rdio-US",
                    "foreign_id": "rdio-US:track:t2840160",
                    "id": "TRXWDUE136E844974E"
                },
                {
                    "foreign_release_id": "rdio-US:release:a224383",
                    "catalog": "rdio-US",
                    "foreign_id": "rdio-US:track:t2714517",
                    "id": "TRVJRZN136E835EB4D"
                }
            ],
            "artist_id": "AR633SY1187B9AC3B9",
            "id": "SOSJAHD13770F4D40C"
        }
    ]
  }
}

Creates a dynamic artist playlist for weezer. Send all user feedback to a catalog:

http://developer.echonest.com/api/v4/playlist/dynamic/create?api_key=YOUR_API_KEY&artist=weezer&type=artist-radio&session_catalog=CAKSMUX1321A708AA4

dynamic/restart

Restarts a playlist session. Given the session ID and a new set of playlist parameters, this method restarts the playlist session based upon the new parameters. The session history is maintained. Everything else is reset. This method takes all the same parameters as dynamic/create, plus the session ID. Returns the given session ID.

Here's an example:

Resets the playlist session with a new seed artist

http://developer.echonest.com/api/v4/playlist/dynamic/restart?api_key=YOUR_API_KEY&artist=deerhoof&type=artist-radio&session_id=7bf982d80ed8421c8c94dbd6de565e9d

Returns:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "session_id": "7bf982d80ed8421c8c94dbd6de565e9d",
     }
 }

dynamic/next

Returns the next songs in the playlist. Results includes two lists of songs - one list (called next) contains the next songs to play, the other (called lookahead) contains the lookahead songs (controlled via the lookahead parameter). The next songs returned by this method will be considered to be played starting at the time the call returns. Use the dynamic/feedback method to indicate that the song was skipped or not played.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY your API key
format no no json, xml, jsonp the format of the returned playlist
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
results no no 0 - 1 - 5 the desired number of next songs returned. See below for discussion on why you can request zero results
lookahead no no 0 to 5 number of lookahead songs to return. Lookahead songs are the next songs that will be returned to be played if no user feedback or steering occurs before the next dynamic/next method call.

Gets the next song in the playlist:

http://developer.echonest.com/api/v4/playlist/dynamic/next?api_key=YOUR_API_KEY&format=json&session_id=3c717a4465dc4a2ba871747a2044f441

This returns:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "session_id": "3c717a4465dc4a2ba871747a2044f441",
        "songs": [
            {
                "title": "Wolf Like Me",
                "artist_name": "TV On The Radio",
                "artist_id": "AR0970234524234",
                "id": "SOHBJ&R1H808C909D4"
            },
        ]
     }
 }

Use the lookahead parameter to get an advanced look at what may be coming next:

http://developer.echonest.com/api/v4/playlist/dynamic/next?api_key=YOUR_API_KEY&format=json&session_id=3c717a4465dc4a2ba871747a2044f441&lookahead=2&results=2

This returns:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "session_id": "3c717a4465dc4a2ba871747a2044f441",
        "songs": [
            {
                "title": "Wolf Like Me",
                "artist_name": "TV On The Radio",
                "artist_id": "AR0970234524234",
                "id": "SOHBJ&R1H808C909D4"
            },
            {
                "title": "This Is A Call'",
                "artist_name": "Foo Fighters",
                "artist_id": "AR6XPWV1187B9ADAEB",
                "id": "SOMPOYK1280ED5098B"
            }
        ],
        "lookahead": [
            {
                "title": "Dreamin'",
                "artist_name": "Weezer",
                "artist_id": "AR633SY1187B9AC3B9",
                "id": "SOHBJKR1280EC909D4"
            },
            {
                "title": "Life in a glasshouse",
                "artist_name": "Radiohead",
                "artist_id": "ARH6W4X1187B99274F",
                "id": "SOAPCKQ127F3E1B7A8"
            }
        ]
     }
 }

Requesting zero results - Requesting zero results, when combined with a non-zero lookahead, allows you to retrieve the next 1-5 songs without any assumptions about songs being played. Requesting zero results returns the lookahead only, no 'results' will be returned. No songs are assumed played nor are any added to the history or any associated session catalogs. The playlist is not advanced. Making consecutive dynamic/next calls with zero results will return the exact same set of lookahead tracks. You must provide feedback (via the dynamic/feedback api), to explicitly play and/or skip songs in the playlist in order to advance the playlist when 'results' is set to zero.

dynamic/feedback

Give feedback on the given items (artists or songs) or the last played song. This method allows you to give user feedback such as rating, favoriting, banning of a song or artist. Feedback is applied to the item specified by the given song_id or track_id. If no song_id or track_id is specified, then the feedback is applied to the most recent song returned by dynamic/next. Multiple feedbacks can be given at any time. Specified songs need not be in the session history. This allows the pre-seeding of a session with played tracks, skipped tracks, favorites, ratings and bans.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY your API key
format no no json, xml, jsonp the format of the returned playlist
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
ban_artist no yes ARH6W4X1187B99274F SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given artist, or the artist associated with the given song or track is banned from the session and will never appear again. Use last to ban the artist of the most recently returned song.
favorite_artist no yes ARH6W4X1187B99274F SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given artist, or the artist associated with the given song or track is favorited. Use last to favorite the artist of the most recently returned song.
ban_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given song is banned from the session and will never appear again. Use last to ban the most recently returned song.
skip_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song if the given song is in the session history, it is considered to be skipped. The play timestamp of subsequent songs in the session history are adjusted to reflect the skipped song. The skipped song will never appear again in the session. Use last to skip the most recently returned song.
favorite_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given song is favorited. Use last to favorite the most recently returned song
play_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 the given song is considered played. It is not normally necessary to mark songs as played, all songs returned by dynamic/next are automatically considered played. However, you can use the 'played' operation to pre-seed the song history.
unplay_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song this given song is considered not played. Unlike the skip_song operation, the song may appear again in the session. This operation is typically used when a song is retreived by the dynamic/next call but for whatever reason is not actually played in the client. Use last to unplay the most recently returned song.
rate_song no yes SOCZMFK12AC468668F^1 TRTLKZV12E5AC92E11^5 or last^7 the given rating is applied to the song Ratings are of the form: song_id^rating where rating is a value between 0 and 10. Use last to rate the most recently returned song.
update_catalog no no true, false This parameter controls whether or not this given feedback is pushed to the session_catalog. By default, all feedback is pushed to the session_catalog. If this parameter is false then feedback is not pushed to the catalog. This parameter has no effect if there is no session_catalog associated with the playlist session.
invalidate_song no yes SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given song is removed from the play history and will never appear again in the playlist session. This feedback is typically used to discard a song that is unplayable.
invalidate_artist no yes ARH6W4X1187B99274F SOCZMFK12AC468668F TRTLKZV12E5AC92E11 or last for the most recently returned song The given artist, or the artist associated with the given song or track is removed from the play history and will never appear again in this playlist session. This feedback is typically used to discard an artist that is unplayable.

Examples:

Skip the most recently returned song:

http://developer.echonest.com/api/v4/playlist/dynamic/feedback?api_key=YOUR_API_KEY&format=json&session_id=3c717a4465dc4a2ba871747a2044f441&skip_song=last

This returns a simple status block:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
     }
 }

Rate the given song with a 9 rating:

http://developer.echonest.com/api/v4/playlist/dynamic/feedback?api_key=YOUR_API_KEY&format=json&session_id=3c717a4465dc4a2ba871747a2044f441&rate_song=SOCZMFK12AC468668F^9

Ban artists for some songs:

http://developer.echonest.com/api/v4/playlist/dynamic/feedback?api_key=YOUR_API_KEY&format=json&session_id=3c717a4465dc4a2ba871747a2044f441&ban_artist=SO543254321234&ban_artist=SO123411212376

dynamic/steer

Steers the playlist based upon the given constraints. Steerings are additive and can be reset with the reset parameter.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY your API key
format no no json, xml, jsonp the format of the returned playlist
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
min_xxx no yes min_song_hotttnesss=0.8 prefer songs that have a value for xxx that is greater than or equal to the given value where xxx can be tempo, loudness, danceability, energy, liveness, speechiness, acousticness, song_hotttnesss, artist_hotttnesss, artist_familiarity
max_xxx no yes max_tempo=129 prefer songs that have a value for xxx that is less than or equal to the given value where xxx can be tempo, loudness, danceability, energy, liveness, speechiness, acousticness, song_hotttnesss, artist_hotttnesss, artist_familiarity
target_xxx no yes target_energy=0.7 prefer songs that have a value for xxx that are closer to the given value where xxx can be tempo, loudness, danceability, energy, liveness, speechiness, acousticness, song_hotttnesss, artist_hotttnesss, artist_familiarity
more_like_this no yes SO123412341234, SO12341234^2 prefer songs that are similar to the given song ID with the given optional boost. song_id can be last to use the most recently returned song. Boost can be an integer between 0 and 5. The default is 1.
less_like_this no yes SO123412341234, SO12341234^2 prefer songs that are less similar to the given song ID with the given optional boost. song_id can be last to use the most recently returned song. Boost can be an integer between 0 and 5. The default is 1.
adventurousness no no 0 - 1 adjust the adventurousness of the session. A value of 0 means no adventurousness, only known and preferred music will be played. A value of 1 means high adventurousness, mostly unknown music will be played. This parameter only applies to catalog and catalog-radio type playlists.
variety no no 0 - 1 adjust the variety of the session. A higher number will allow for more variety in the artists.
description no yes alt-rock,-emo,harp^2 prefer songs by artists that match the given general description
style no yes jazz, metal^2 prefer songs by artists that match the given style
song_type no yes christmas, live, studio prefers songs that match the given song type. Supported song_types are: 'christmas', 'live', 'studio'. A song type can optionally be followed by ':' and a state, where the state can be one of 'true', 'false', 'seed' or 'any'. If no state is given, the desired state is assumed to be 'true'.
mood no yes happy, sad^.5 prefer songs by artists that match the given mood
reset no no false, true resets any playlist steering that has been done on this session to the default state

Examples:

Steer the playlist toward songs with a tempo faster than 120BPM

http://developer.echonest.com/api/v4/playlist/dynamic/steer?api_key=YOUR_API_KEY&min_tempo=120&session_id=3c717a4465dc4a2ba871747a2044f441

This returns a simple status block:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
     }
 }

Steer the playlist toward songs that are similar to 'Life in a Glass House' by Radiohead

http://developer.echonest.com/api/v4/playlist/dynamic/steer?api_key=YOUR_API_KEY&more_like_this=SOAPCKQ127F3E1B7A8&session_id=3c717a4465dc4a2ba871747a2044f441

Steer the playlist away from songs that are similar to 'Island in the Sun' by Weezer

http://developer.echonest.com/api/v4/playlist/dynamic/steer?api_key=YOUR_API_KEY&less_like_this=SOBSLVH12A8C131F38&session_id=3c717a4465dc4a2ba871747a2044f441

Steer the playlist toward songs that have the highest energy, danceability and loudness

http://developer.echonest.com/api/v4/playlist/dynamic/steer?api_key=YOUR_API_KEY&session_id=3c717a4465dc4a2ba871747a2044f441&target_loudness=1&target_energy=1&target_danceability=1

dynamic/info

Returns information about a dynamic playlist session

Parameter Required? Multiple? Values Description
session_id yes no id return by previous playlist/dynamic/create call The session id of interest
format no no json, xml, jsonp the format of the results
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example:

Get info for a dynamic playlist:

http://developer.echonest.com/api/v4/playlist/dynamic/info?api_key=YOUR_API_KEY&session_id=c1fdacd5a1164449b49584398ca807f3

This returns:

{
    "response": {
        "banned_artist_ids": [
            "AR1K0Q41187B989030"
        ],
        "id": "4fe0f898cce44622bd8e2f5b24e7a364",
        "banned_song_ids": [],
        "constraints": ,
        "favorited_artist_ids": [],
        "favorited_song_ids": [],
        "favorites_map": {},
        "rulesets" : [
            "RS12341234", "RS2345123", 'RS32345234'
        ],
        "options": {
            "adventurousness": 0.2,
            "artist_pick": "song_hotttnesss-desc",
            "buckets": [],
            "distribution": "focused",
            "limited_interactivity": false,
            "limit": "false",
            "playlist_type": "artist-radio",
            "rank_type": "relevance",
            "sort": null,
            "variety": 0.5
        },
        "ratings_map": {
            "SOAGDSM12AB017E9AC": 10,
            "SOAPCKQ127F3E1B7A8": 10,
            "SOBSLVH12A8C131F38": 0
        },
        // ...
    }
}

dynamic/delete

Deletes a previously created session. A non-commercial API can have, at most 1,000 active playlist sessions.

Parameter Required? Multiple? Values Description
session_id yes no id return by previous playlist/dynamic/create call The session id of interest
format no no json, xml, jsonp the format of the results
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example:

Delete a playlist session

http://developer.echonest.com/api/v4/playlist/dynamic/delete?api_key=YOUR_API_KEY&session_id=c1fdacd5a1164449b49584398ca807f3

This returns a simple status block:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
     }
 }