Api calls for generating playlists
Returns a basic playlist. A basic playlist is generated once from an initial set of parameters, and returned as an ordered list of songs. Basic playlist functionality is supported, see the static and dynamic playlist APIs for advanced contextual and personalized playlisting.
Some properties of a basic 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 N6E4NIOVYMTHNDM8J 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-radio, song-radio the type of the playlist to be generated. See below for details on each of the types - the type of playlist to be generated artist_id no yes (no more than 5 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 (See Project Rosetta Stone) 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 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 (See Project Rosetta Stone) 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 (See Project Rosetta Stone) results no no 0 - 100 (default = 15) the desired number of songs in the playlist bucket no yes id:catalog-name, tracks specifies which rosetta id space info should be returned limit no no true, false if 'true', limit the results to any of the given rosetta id space dmca no no true, false If true the playlist delivered will meet the DMCA 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. See Project Rosetta Stone for more information on ID spaces.
- Playlist Types:
- artist-radio - plays songs for the given artists and similar artists
- song-radio - plays songs similar to the song specified.
Example queries:
Generates an artist radio playlist for Weezer:
http://developer.echonest.com/api/v4/playlist/basic?api_key=N6E4NIOVYMTHNDM8J&artist=Weezer&format=json&results=20&type=artist-radioGenerates a song radio playlist for Weezer's Pork And Beans:
http://developer.echonest.com/api/v4/playlist/basic?api_key=N6E4NIOVYMTHNDM8J&song_id=SOGOCHA12AF72A3A99&format=json&results=20&type=song-radioHere 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 radio playlist for weezer, with tracks from the 7Digital catalog
http://developer.echonest.com/api/v4/playlist/basic?api_key=N6E4NIOVYMTHNDM8J&artist=weezer&format=json&results=2&type=artist-radio&bucket=id:7digital-US&bucket=tracks&limit=trueHere is an example json response:
{ "response": { "songs": [ { "artist_id": "AR633SY1187B9AC3B9", "artist_name": "Weezer", "id": "SOTPDRE12AB01893E1", "title": "Lullabye For Wayne (Pre-Production Recording)", "tracks": [ { "catalog": "7digital-US", "foreign_id": "7digital-US:track:7504103", "id": "TRPKZCA12903CCE63F", "preview_url" : "http://path.to.30.second.sample.mp3", "release_image" : "http://path.to.cover.art/image.jpg", "audio" : "http://path/to/full/stream.mp3" } ] }, { "artist_id": "AR633SY1187B9AC3B9", "artist_name": "Weezer", "id": "SOJKBXX12A67020689", "title": "Crab", "tracks": [ { "catalog": "7digital-US", "foreign_id": "7digital-US:track:123924", "id": "TRHUIGV128E078A4BE", "preview_url" : "http://path.to.30.second.sample.mp3", "release_image" : "http://path.to.cover.art/image.jpg", }, ] } ], "status": { "code": 0, "message": "Success", "version": "4.2" } } }
Returns a static playlist. A static playlist is generated once from an initial set of parameters, and returned as an ordered list of songs.
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 N6E4NIOVYMTHNDM8J your API key format no no json, xml, xspf, 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 the type of the playlist to be generated. See below for details on each of the types artist_pick no no song_hotttness-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. variety no no 0 - 1 (default = 0.3) 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 (See Project Rosetta Stone) 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 yes CAKSMUX1321A708AA4 ID of seed artist 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 (See Project Rosetta Stone) 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 (See Project Rosetta Stone) description no yes alt-rock,-emo,harp^2 description of the type of songs that can be included in the playlist style no yes jazz, metal^2 a musical style or genre like rock, jazz, or funky. See the method list_terms for details on what styles are currently available mood no yes happy, sad^.5 a mood like happy or sad. See the method list_terms for details on what moods are currently available 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 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 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 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 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 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 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 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 min_longitude no no -180.0 < longitude < 180.0 the minimum longitude for the location of artists in the playlist max_longitude no no -180.0 < longitude < 180.0 the maximum longitude for the location of artists in the playlist min_latitude no no -90.0 < latitude < 90.0 the minimum latitude for the location of artists in the playlist max_latitude no no -90.0 < latitude < 90.0 the maximum latitude for the location of artists in the playlist 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 bucket no yes audio_summary, artist_familiarity, artist_hotttnesss, artist_location, song_hotttnesss, 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, artist_familiarity-asc, artist_hotttnesss-asc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc, song_hotttness-asc, latitude-asc, longitude-asc, mode-asc, key-asc, tempo-desc, duration-desc, loudness-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 no no true, false If true the playlist delivered will meet the DMCA 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. See Project Rosetta Stone for more information on ID spaces.
- Playlist Types:
- artist - plays songs for the given artists
- artist-radio - plays songs for the given artists and similar artists
- artist-description - plays songs from artists matching the given description
- 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 or a song 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 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 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).
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.75To skip Weezer:
artist=-Weezer id=-AR633SY1187B9AC3B9Example queries:
Plays tracks by Weezer and Radiohead:
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&artist=Weezer&artist=radiohead&format=json&results=20&type=artistGenerates an artist radio playlist for Weezer:
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&artist=Weezer&format=json&results=20&type=artist-radioGenerates a song radio playlist for Weezer's Pork And Beans:
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&song_id=SOGOCHA12AF72A3A99&format=json&results=20&type=song-radioGenerates an artist radio playlist for Weezer, but never play tracks by Muse
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&artist=Weezer&artist=-muse&format=json&results=20&type=artist-radioGenerates a 20 song playlist of popular music from the 70s sorted by increasing tempo
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&description=70s&description=disco&type=artist-description&artist_min_familiarity=.7&sort=tempo-asc&results=20Generates a XSPF playlist of unknown tracks by popular artists
http://developer.echonest.com/api/v4/playlist/static?api_key=N6E4NIOVYMTHNDM8J&type=artist-description&description=70s&description=disco&artist_min_hotttnesss=.7&artist_pick=artist_hotttnesss-asc&format=xspf&bucket=id:7digital-US&bucket=tracks&limit=trueCatalog 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4Play 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4&adventurousness=.8Play 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog&seed_catalog=CAKSMUX1321A708AA4&adventurousness=0Catalog 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7&artist=weezerAuto 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7Auto 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=N6E4NIOVYMTHNDM8J&results=20&type=catalog-radio&seed_catalog=CAABOUD13216257FC7&adventurousness=.9Here 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=N6E4NIOVYMTHNDM8J&artist=weezer&format=json&results=2&type=artist&bucket=id:7digital-US&bucket=tracks&limit=trueHere is an example json response:
{ "response": { "songs": [ { "artist_id": "AR633SY1187B9AC3B9", "artist_name": "Weezer", "id": "SOTPDRE12AB01893E1", "title": "Lullabye For Wayne (Pre-Production Recording)", "tracks": [ { "catalog": "7digital-US", "foreign_id": "7digital-US:track:7504103", "id": "TRPKZCA12903CCE63F", "preview_url" : "http://path.to.30.second.sample.mp3", "release_image" : "http://path.to.cover.art/image.jpg", "audio" : "http://path/to/full/stream.mp3" } ] }, { "artist_id": "AR633SY1187B9AC3B9", "artist_name": "Weezer", "id": "SOJKBXX12A67020689", "title": "Crab", "tracks": [ { "catalog": "7digital-US", "foreign_id": "7digital-US:track:123924", "id": "TRHUIGV128E078A4BE", "preview_url" : "http://path.to.30.second.sample.mp3", "release_image" : "http://path.to.cover.art/image.jpg", }, ] } ], "status": { "code": 0, "message": "Success", "version": "4.2" } } }Here is an example XSPF response:
<playlist version="1" xmlns="http://xspf.org/ns/0/"> <trackList> <track> <creator>Veruca Salt</creator> <image>http://echonest-imgdb.s3.amazonaws.com/ARPWTAD1187B9A6B1B-SMALL.jpg</image> <title>So Weird</title> <location>http://path/to/song/so+weird.mp3</location> </track> <track> <creator>Weezer </creator> <image>http://echonest-imgdb.s3.amazonaws.com/ARPWTAD1187B9A6B1B-SMALL.jpg</image> <title>Dreamin</title> <location>http://path/to/song/dreamin.mp3</location> </track> </trackList> </playlist>
Returns a dynamic playlist. A dynamic playlist is created with an initial set of parameters and songs are fetched one at a time using a session identifier. The playlist is dynamic and will return songs based on the listener's feedback.
A dynamic playlist returns a single song at a time along with the session ID. When the client is ready to play the next song it makes a dynamic playlist request that includes the session ID. The dynamic playlist will adapt the playlist based upon a number of factors:
- Skipped songs
- Rated songs
- DMCA Rules
- Played songs
The playlist/dynamic method accepts the same set of parameters as static playlists as well as a few additional parameters described here:
Parameter Required? Multiple? Values Description session_id no no id return by previous playlist/dynamic call The id of the current playlist session. To start a new session, call playlist/dynamic with no session ID. dmca no no true, false If true the playlist delivered will meet the DMCA rules (see below). Setting this parameter on a prexisting session resets the playlist session. 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. Setting this parameter on a prexisting session resets the playlist session. rating no no 1,2,3,4 or 5 The user rating for the previous track. 5 is the highest rating, 1 is the lowest rating. Some playlist algorithms will adapt playlists based upon these ratings. chain_xspf no no true or false If true, an additional 'track' is added to the end XSPF playlist that is a URL to the next XSPF in the chain. steer no yes tempo, loudness, danceability, energy, song_hotttnesss, artist_hotttnesss, artist_familiarity (plus multiplier, see description) Using the previously played track as the basis, make all future tracks some multiplier of the selected attribute(s). required terms use a multiplier in a boost-like format - e.g. energy^.5 to make all future songs have half the energy of the previously played song, or loudness^1.3 to add 30%. steer_description no yes alt-rock, -emo, harp^2, country^0 Using the current playlist as a basis, add or remove terms relating to the artists and songs to be played. Applying a term again will overwrite the previous term, including boost. Boosting with a "0" will remove a term from the list of qualifiers. Using 'description' rather than 'steer_description' will clear the description list and restart the playlist session with the new term. steer_style no yes alt-rock, -emo, harp^2, country^0 Using the current playlist as a basis, add or remove terms relating to the style of artists and songs to be played. Applying a style again will overwrite the previous style, including boost. Boosting with a "0" will remove a term from the list of qualifiers. Using 'style' rather than 'steer_style' will clear the style list and restart the playlist session with the new style. steer_mood no yes happy, -sad, angry^2, chill^0 Using the current playlist as a basis, add or remove terms relating to the mood of artists and songs to be played. Applying a mood again will overwrite the previous mood, including boost. Boosting with a "0" will remove a mood from the list of moods. Using 'mood' rather than 'steer_mood' will clear the mood list and restart the playlist session with the new mood. ban no yes song, artist Banning will prevent the song/all songs by that artist from appearing again in the current playlist session.
- DMCA: When the DMCA 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
When a dynamic playlist request is made, a single song is returned along with a session ID. To get the next song in the playlist, a dynamic request with the session ID is made. After creating the initial playlist, the only parameters necessary to fetch songs are the api key, session ID, and format. If parameters like artist, artist_id, song, or description are provided, the api will interpret this as a request to create a new playlist on the same session. Some parameters are 'steering' parameters and will adjust the current playlist as opposed to resetting it. The parameters that you can use within an existing session to steer a playlist without resetting the sesion are:
- session_id
- rating
- steer
- steer_description
- steer_style
- steer_mood
- ban
- chain_xspf
Here's an example:
Generates an artist playlist for weezer:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&artist=weezer&type=artist-radioReturns:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "session_id": "7bf982d80ed8421c8c94dbd6de565e9d", "songs": [ { "title": "Dreamin'", "artist_name": "Weezer", "artist_id": "AR633SY1187B9AC3B9", "id": "SOHBJKR1280EC909D4" }, ] } }The next song in the playlist can be retrieved with the request:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&session_id=7bf982d80ed8421c8c94dbd6de565e9dWhich returns:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "session_id": "1241234abcdabde", "songs": [ { "title": "Sing For Absolution", "artist_name": "Muse", "artist_id": "ARR3ONV1187B9A2F59", "id": "SOLGISP128CB7B06E3" }, ] } }
When a playlist comes to an end, for a session, the playlist/static call will return an empty song list. A session can be reconfigured to return a different playlist at anytime by invoking playlist/dynamic with a new set of parameters.
Some more example queries:
Create a new dynamic artist-radio playlist for weezer:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&artist=weezer&format=json&type=artist-radioThis returns:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "session_id": "3c717a4465dc4a2ba871747a2044f441", "songs": [ { "title": "Pork and Beans'", "artist_name": "Weezer", "artist_id": "AR12341123423416", "id": "SOHBJKR1280EC909D4" }, ] } }Gets the next song in the playlist:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&format=json&session_id=3c717a4465dc4a2ba871747a2044f441This 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" }, ] } }Starts a new playlist on the same session:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&artist=weezer&artist=muse&format=json&session_id=3c717a4465dc4a2ba871747a2044f441Apply a user rating to the last returned track:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&rating=1&session_id=3c717a4465dc4a2ba871747a2044f441Ban the artist of the last returned track:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&ban=artist&session_id=3c717a4465dc4a2ba871747a2044f441Steer the playlist to songs with a tempo 20% faster than the last track:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&steer=tempo^1.2&session_id=3c717a4465dc4a2ba871747a2044f441Add a description to (steer) the existing description list:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&steer_description=-emo&session_id=3c717a4465dc4a2ba871747a2044f441Creates a chained XSPF Playlist:
http://developer.echonest.com/api/v4/playlist/dynamic?api_key=N6E4NIOVYMTHNDM8J&artist=weezer&format=xspf&type=artist&bucket=id:7digital-US&chain_xspf=true&bucket=tracks&limit=trueThis returns an XSPF playlist like so:
<playlist version="1" xmlns="http://xspf.org/ns/0/"> <trackList> <track> <creator>Weezer</creator> <title>Kids/Pokerface</title> <location>http://path/to/mp3.mp3</location> </track> <track> <location>http://developer.echonest.com/api/v4/playlist/dynamic?api_key=8TPE3VC60ODJTNTFE&format=xspf&session_id=61312557372043d09780de749e3a7181</location> <title>More like weezer</title> </track> </trackList> </playlist>
Returns state information for dynamic playlists.
Parameter Required? Multiple? Values Description session_id yes no id return by previous playlist/dynamic call The id of the current playlist session. To start a new session, call playlist/dynamic with no session ID. 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 session info for a dynamic playlist:
http://developer.echonest.com/api/v4/playlist/session_info?api_key=N6E4NIOVYMTHNDM8J&session_id=c1fdacd5a1164449b49584398ca807f3This returns:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "terms": [{ "frequency": 1.0, "name": "rock" }, { "frequency": 0.71378867608195351, "name": "alternative" }, { "frequency": 0.69095668193199911, "name": "alternative rock" }, { "frequency": 0.65668272782813841, "name": "indie" }, { "frequency": 0.64766399493540405, "name": "indie rock" }, { "frequency": 0.61232526472113424, "name": "pop" }, { "frequency": 0.51026002081414024, "name": "punk" }, { "frequency": 0.33250036778616132, "name": "power pop" }, { "frequency": 0.31902738195194952, "name": "emo" }, { "frequency": 0.31391704059473652, "name": "pop rock" }, { "frequency": 0.30739945700325128, "name": "grunge" }, { "frequency": 0.23041887347399467, "name": "soundtrack" }, { "frequency": 0.22837311042124264, "name": "acoustic" }, { "frequency": 0.22022382070655525, "name": "guitar" }, { "frequency": 0.21791384448994017, "name": "hard rock" }, { "frequency": 0.20734542132020858, "name": "electronic" }, { "frequency": 0.20620638149698217, "name": "indie pop" }, { "frequency": 0.19632422057344523, "name": "new wave" }, { "frequency": 0.18508973492552899, "name": "90s" }, { "frequency": 0.18473382084126663, "name": "pop punk" }, { "frequency": 0.17224351527852039, "name": "american" }, { "frequency": 0.17135561535722449, "name": "jazz" }, { "frequency": 0.16903079873464968, "name": "hardcore" }, { "frequency": 0.16198390097464166, "name": "experimental" }, { "frequency": 0.14677949691206213, "name": "instrumental" }, { "frequency": 0.1421983853683873, "name": "classic rock" }, { "frequency": 0.1372265944836682, "name": "electronica" }, { "frequency": 0.13715444847388056, "name": "modern rock" }, { "frequency": 0.12618860220988484, "name": "punk pop" }, { "frequency": 0.11959638026044632, "name": "metal" }, { "frequency": 0.11668085846558782, "name": "singer-songwriter" }, { "frequency": 0.10745519624820681, "name": "hip hop" }, { "frequency": 0.10610794155762615, "name": "ska" }, { "frequency": 0.10517110231419696, "name": "post-grunge" }, { "frequency": 0.10438449913022113, "name": "80s" }, { "frequency": 0.10255617783743638, "name": "funk" }, { "frequency": 0.097947478031036511, "name": "dance" }, { "frequency": 0.094503575393161524, "name": "country" }, { "frequency": 0.090790867540085085, "name": "psychedelic" }, { "frequency": 0.083041279179575878, "name": "blues" }, { "frequency": 0.081892954317720659, "name": "alternative pop rock" }, { "frequency": 0.081026488940155392, "name": "ambient" }, { "frequency": 0.080174964390734557, "name": "piano rock" }, { "frequency": 0.078974899883130098, "name": "california" }, { "frequency": 0.078246028105182552, "name": "classic" }, { "frequency": 0.077151062748579427, "name": "united states" }, { "frequency": 0.074835844268721613, "name": "progressive rock" }, { "frequency": 0.074826282548542275, "name": "noise pop" }, { "frequency": 0.072881570284492408, "name": "folk" }, { "frequency": 0.07232616366067135, "name": "soul" }, { "frequency": 0.071751310483442479, "name": "garage rock" }, { "frequency": 0.071152784717570847, "name": "rap" }, { "frequency": 0.068413820520809576, "name": "chill-out" }, { "frequency": 0.067575912746499572, "name": "piano" }, { "frequency": 0.067208796683664362, "name": "male vocalist" }, { "frequency": 0.066820869490416185, "name": "00s" }, { "frequency": 0.06297434389951026, "name": "trip hop" }, { "frequency": 0.061302531571268519, "name": "hardcore punk" }, { "frequency": 0.057403240335956361, "name": "heavy metal" }, { "frequency": 0.05701438705589032, "name": "chicago" }, { "frequency": 0.055265503191344018, "name": "british pop" }, { "frequency": 0.054837283282155994, "name": "noise" }, { "frequency": 0.053086173760937501, "name": "funny" }, { "frequency": 0.052642459353716801, "name": "house" }, { "frequency": 0.050893604092999783, "name": "punk revival" }, { "frequency": 0.048124396945421387, "name": "college rock" }, { "frequency": 0.047690438894100941, "name": "comedy rock" }, { "frequency": 0.045332097359129034, "name": "beautiful" }, { "frequency": 0.044463743706655151, "name": "post-hardcore" }, { "frequency": 0.043472596865702283, "name": "soft rock" }, { "frequency": 0.041768595030146613, "name": "glam rock" }, { "frequency": 0.041768595030146613, "name": "oldies" }, { "frequency": 0.0412299784376731, "name": "breakbeat" }, { "frequency": 0.04116230880218321, "name": "industrial" }, { "frequency": 0.040337378384973643, "name": "trance" }, { "frequency": 0.040072855162149194, "name": "folk rock" }, { "frequency": 0.039223459052319228, "name": "post rock" }, { "frequency": 0.03882218487585886, "name": "drum and bass" }, { "frequency": 0.038293557141114751, "name": "downtempo" }, { "frequency": 0.037674499131549154, "name": "dream pop" }, { "frequency": 0.036657857163671384, "name": "blues-rock" }, { "frequency": 0.036320971632124076, "name": "female vocalist" }, { "frequency": 0.035560508632410406, "name": "lo-fi" }, { "frequency": 0.034043905997630179, "name": "japanese" }, { "frequency": 0.032735575005635405, "name": "synthpop" }, { "frequency": 0.032045073661869095, "name": "bass" }, { "frequency": 0.028603166734215899, "name": "surf music" }, { "frequency": 0.027405637932073089, "name": "female" }, { "frequency": 0.027261698761248617, "name": "ballad" }, { "frequency": 0.026468755648966544, "name": "christian" }, { "frequency": 0.026048676185550949, "name": "comedy" }, { "frequency": 0.026011231653848395, "name": "los angeles" }, { "frequency": 0.024969915380155021, "name": "shoegaze" }, { "frequency": 0.024882377480574615, "name": "italy" }, { "frequency": 0.024291952918233661, "name": "experimental rock" }, { "frequency": 0.023436010208923434, "name": "rock 'n roll" }, { "frequency": 0.023378429806138652, "name": "dance rock" }, { "frequency": 0.022742637136285111, "name": "skacore" }, { "frequency": 0.022742637136285111, "name": "jungle music" }, { "frequency": 0.02221207591779616, "name": "north carolina" }], "description": [], "seed_songs": [], "banned_artists": ["ARNRPX81187FB5CE09"], "rules": [{ "rule": "Don't put two copies of the same song in a playlist." }, { "rule": "Give preference to artists that are not already in the playlist" }], "session_id": "c1fdacd5a1164449b49584398ca807f3", "seeds": ["AR633SY1187B9AC3B9"], "skipped_songs": [{ "served_time": 1291233888.934294, "artist_id": "ARSPUJF1187B9A14B8", "id": "SOOYDAZ12A58A7AE08", "artist_name": "Death Cab for Cutie", "title": "I Will Follow You into the Dark (Album Version)" }, { "served_time": 1291233915.4518731, "artist_id": "ARBK9N71187B99B9AE", "id": "SOUTUGY12A58A78912", "artist_name": "Size 14", "title": "People Get Really Drunk In Las Vegas" }, { "served_time": 1291233922.2778349, "artist_id": "ARKLKMU1187FB4EF65", "id": "SONGJXQ12A58A799F7", "artist_name": "OK Go", "title": "What To Do" }], "banned_songs": [{ "served_time": 1291233915.4518731, "artist_id": "ARBK9N71187B99B9AE", "id": "SOUTUGY12A58A78912", "artist_name": "Size 14", "title": "People Get Really Drunk In Las Vegas" }], "playlist_type": "artist-radio", "seed_catalogs": [], "rated_songs": [], "history": [{ "served_time": 1291233873.952306, "artist_id": "ARTH2D01187B98D865", "id": "SOMMIKO12AB01827FC", "artist_name": "Everclear", "title": "I Will Buy You A New Life" }, { "served_time": 1291233888.934294, "artist_id": "ARSPUJF1187B9A14B8", "id": "SOOYDAZ12A58A7AE08", "artist_name": "Death Cab for Cutie", "title": "I Will Follow You into the Dark (Album Version)" }, { "served_time": 1291233891.8415, "artist_id": "ARNRPX81187FB5CE09", "id": "SOUOGBJ12A58A7D64A", "artist_name": "We Shot the Moon", "title": "The Brightside" }, { "served_time": 1291233904.8374181, "artist_id": "AR633SY1187B9AC3B9", "id": "SOBSLVH12A8C131F38", "artist_name": "Weezer", "title": "Island In The Sun" }, { "served_time": 1291233915.4518731, "artist_id": "ARBK9N71187B99B9AE", "id": "SOUTUGY12A58A78912", "artist_name": "Size 14", "title": "People Get Really Drunk In Las Vegas" }, { "served_time": 1291233922.2778349, "artist_id": "ARKLKMU1187FB4EF65", "id": "SONGJXQ12A58A799F7", "artist_name": "OK Go", "title": "What To Do" }, { "served_time": 1291233931.589036, "artist_id": "ARIDDOM1187B9A1360", "id": "SOSVAUK12A6D4F5FCB", "artist_name": "We Are Scientists", "title": "the great escape" }] } }