/v2/playlist

Introduction to Playlists

Playlists are lists of music or sound tracks that have been created by, or for, a Portal. Playlists facilitate music searches because they are songs that have been selected to fit a mood or occasion, as defined in the description of the list.

Playlists are owned by a Portal. The Portal creating the list may keep it private, or share it. For example, if Rumblefish creates a special occasion Playlist, intended for all Portals to use, we will share it. Playlists default to private, in case a Portal does not wish to share their curation efforts with other portals.

Shared Playlists from other Portals, or Playlists you are constructing, may need to be hidden from your users. You may "enable" other Portals' shared Playlists or your "owned" playlists, in order to control access. This is the purpose of the filter parameter.

If you query an individual id or legacy_id, the response includes the Playlist media. If you query without a specific Playlist ID you will receive a list of Playlists.

GET

Parameter Options Response
none A list of Playlists that are shared.
id A list of Media for that Playlist, if it is shared.
legacy_id A list of Media for that Playlist, if it is shared.
token A list of Playlists that are owned by the Portal.
id & token Playlist details (A list of Media for that Playlist), if it is owned by the Portal.
filter all, owned, enabled Filters Access to Playlists for a Portal.
q Search by playlist title or editorial.
start The offset to start listing from.
sort title Sort results by the specified field.
direction asc, desc The direction to sort.

Usage

Playlist details are a JSON object structured as follows:

  {
    "playlist" : {
      "id" : 183,
	  "legacy_id" : 123,
      "title" : "Summer Fun #12",
      "editorial" : "Great tracks for a summer scene!",
      "picked" : false,
      "image_url" : "...",
	  "shared" : true,
	  "owner" : true,
      "media" : [
      { 
        "id" : 13076, 
        "provider_reference" : null,
         "title":"CMI8789 It's Good To Be",
         "genre":"Pop",
         "bpm":120,
         "duration":163,
         "track":null,
         "lyrics":null,
         "original_filename" : "CMI.8789.It s Good To Be.wav",
         "grid":null,
         "isrc":null,
         "iswc":null,
         "upc":null,
         "explicit":false,
         "preview_url": "...",
         "waveform_url": "...",
         "picked": false
       },
		  ...
      ]
    }
  }
  

Lists of Playlists are a JSON object structured as follows:

  {
    "playlists" : 
	  [ 
		{
	      "id" : 183,
	      "title" : "Summer Fun #12",
	      "editorial" : "Great tracks for a summer scene!",
              "picked" : true,
	      "image_url" : "...",
		  "media_count" : 10, 
		  "owner" : true
		},
		{
	      "id" : 2,
	      "title" : "Example Shared Playlist",
	      "editorial" : "Awesome Tracks for your Videos!",
              "picked" : false,
	      "image_url" : null,
		  "media_count" : 4, 
		  "owner" : false
		} 
	  ],
	"playlist_count": 2
  }

  

The picked field indicates if the media record is a featured item, promoted by the Rumblefish editorial staff. For any list of media, featured items will be the first listed.

Try It!