Basic Playlisting

Basic Playlisting, our entry-level playlisting API method allows you to integrate very simple and straightforward music playlisting or radio features within your application. The Basic Playlisting solution relies on this single API method to return a set of playlist results, enabling you to stream the playlist to the given end user. Playlist results may be constrained to the customer's complete music catalog. A demonstration of basic playlisting can be found here:

Basic Playlisting Demo

basic

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 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-radio, song-radio , genre-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
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
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.
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
results no no 0 - 100 (default = 15) the desired number of songs in the playlist
bucket no yes id:catalog-name, tracks specifies which extra information should be returned 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, styleb 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-radio - plays songs for the given artists and similar artists
  • song-radio - plays songs similar to the song specified.
  • genre-radio - plays songs from artists matching the given genre

Example queries:

Generates an artist radio playlist for Weezer:

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

Generates an genre radio playlist for dance pop:

http://developer.echonest.com/api/v4/playlist/basic?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

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

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

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 radio playlist for weezer, with tracks from the 7Digital catalog

http://developer.echonest.com/api/v4/playlist/basic?api_key=YOUR_API_KEY&artist=weezer&format=json&results=2&type=artist-radio&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"
        }
    }
}