Recommendations-api/v2.1/playlist

Jump to: navigation, search

Playlist

Returns a playlist of songs based on a seed item, which can be a song, album, artist, or any of hundreds of music attributes. Parameters in the request let you space out the songs from a single artist or album, and restrict the number of songs from a single artist or album.

The hundreds of music attributes you can use to seed a playlist include the following:

  • styles
hundreds of styles such as goth rock, smooth soul, and progressive bluegrass.
  • moods
hundreds of moods such as bittersweet, cosmopolitan, and meditative.
  • themes
dozens of themes such as family, goodbyes, and road trip.
  • genres
dozens of genres such as rap, holiday, and classical.
  • subgenres  
hundreds of subgenres such as salsa, musique concrète, and contemporary blues.

Playlist randomizes results within the criteria you specify, so repeat requests return different results and different sequences of results.

This request returns a large amount of data, especially if you use the include parameter to return additional data. To speed data transmission, do the following:

  • Request only data you need.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

Syntax

music/playlist? nameid=nameid
trackid=trackid
albumid=albumid
attributeid=attributeid
&apikey=apikey&sig=sig&entitytype=entitytype [&playlist-quota-album=playlist-quota-album] [&playlist-separation-album=playlist-separation-album] [&playlist-quota-artist=playlist-quota-artist] [&playlist-separation-artist=playlist-separation-artist] [&playlist-strict=playlist-strict] [&include=include] [&format=format] [&country=country] [&language=language] [&size=size]

Request Example 1

Request a playlist of 15 songs based on the Adult Contemporary R&B subgenre and include a sample of each song.

Request Example 2

Request a playlist based on Justin Bieber's album Believe with at least four songs between songs on the same album and no more than three songs on the same album.

Request Example 3

Request a playlist of 30 songs based on the Delta Blues music style with at least five songs between songs by the same artist and no more than four songs by the same artist.

Request Example 4

Request a playlist based on the Broken Water song Drown in an XML response.

Request Example 5

Request a playlist based on the singer Terri Nunn and include any reviews available.

Request Parameters

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
entitytype Yes Type of content to look for. This request recognizes only song.
sig Yes A calculated authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.

albumid Conditional Rovi Music ID for an album, consisting of the prefix MW followed by a ten-digit number, specified like this: albumid=MW0000056882.

You can grab album IDs from responses to the following requests:

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • attributeid
attributeid Conditional Rovi Music ID for a music mood, style, theme, genre, or subgenre. Attribute IDs consist of the prefix MA or XA followed by a ten-digit number, specified like this: attributeid=MA0000002504 or attributeid=XA0000001029.

For a list of music moods, see the Music Moods table.

For a list of music themes, see the Music Themes table.

For a list of music genres, subgenres, and styles, call Descriptor/MusicGenres.

You can also grab attribute IDs from responses to the following requests:

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • attributeid
nameid Conditional Rovi Name ID for a person or group, consisting of the prefix MN followed by a ten-digit number.

Your application can grab name IDs from responses to Search and from Info, Credits, Tracks, and Recommendations requests. For a complete list of requests that return name IDs, click here.

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • attributeid
trackid Conditional Rovi Music ID for a song, consisting of the prefix MT followed by a ten-digit number.

Your application can grab track IDs from responses to the following requests:

Condition: The request must contain just one of these parameters:

  • nameid
  • albumid
  • trackid
  • attributeid
country No Country of the language of the response. The current release of the API supports only US.
format No Format of the returned data: json or xml. The default is JSON.

Alternatively you can specify the response format in an HTTP Accept header with either of these Accept field content types:

  • application/xml
  • application/json

If you specify both, the format parameter overrides the Accept header.

include No Additional data to include in each result returned. To include song samples, for example, specify include=sample. For multiple includes, separate the values with commas like this: include=review,sample.

You can include the following data for each song returned:

language No Language of the response data. This request supports only en (English).
playlist-quota-album No Maximum number of songs to select from the same album.
playlist-quota-artist No Maximum number of songs to select from the same artist.
playlist‑separation‑album No Minimum number of songs to place between songs from the same album.
playlist‑separation‑artist No Minimum number of songs to place between songs from the same artist.
playlist-strict No Whether the quota and separation parameters should be followed when results are fewer than the number of results requested by the size parameter: true or false. Default is false.
size No The number of items you want to be returned. The default is 20.

Response

Response Header

ResponseTypeDescription
controlSet ControlSet The HTTP response status.
meta:id string Server transaction ID for the response.

Response for Playlist

ResponseTypeDescription
results result [ ] A playlist of songs.

JSON Response Example

A top response to the request for a playlist with song samples based on a Sunday afternoon theme.
Requested with http://api.rovicorp.com/recs/v2.1/music/playlist?apikey=apikey&sig=sig&entitytype=song&
attributeid=MA0000006310&include=sample&format=json&size=1
.
{
   "playlistResponse":{
      "meta:id":"tul1cpgpsrapp26:gwy:3gzc9p",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"song",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.81136066
               }
            ],
            "id":"MT0013971063",
            "messages":null,
            "song":{
               "ids":{
                  "amgClassicalTrackId":null,
                  "amgPopTrackId":"T 7328443",
                  "isrcId":"USRO20452509",
                  "muzeId":"37591959",
                  "trackId":"MT0013971063"
               },
               "title":"Borderline",
               "primaryArtists":[
                  {
                     "id":"MN0000007031",
                     "name":"Alison Krauss & Union Station"
                  }
               ],
               "isPick":false,
               "genres":[
                  {
                     "id":"MA0000002532",
                     "name":"Country",
                     "weight":9
                  },
                  {
                     "id":"MA0000002613",
                     "name":"Pop\/Rock",
                     "weight":7
                  }
               ],
               "appearances":null,
               "appearancesUri":"http:\/\/api.rovicorp.com\/data\/v1.1\/song\/appearances?format=json&apikey=4p1k3y&trackId=MT0013971063",
               "moods":null,
               "moodsUri":"http:\/\/api.rovicorp.com\/data\/v1.1\/song\/moods?format=json&apikey=4p1k3y&trackId=MT0013971063",
               "review":null,
               "reviewUri":null,
               "styles":null,
               "stylesUri":"http:\/\/api.rovicorp.com\/data\/v1.1\/song\/styles?format=json&apikey=4p1k3y&trackId=MT0013971063",
               "themes":null,
               "themesUri":"http:\/\/api.rovicorp.com\/data\/v1.1\/song\/themes?format=json&apikey=4p1k3y&trackId=MT0013971063"
            }
         }
      ]
   }
}

XML Response Example

Two songs in response to the request for a playlist based on the singer Terri Nunn along with any reviews available.
Requested with http://api.rovicorp.com/recs/v2.1/music/playlist?apikey=apikey&sig=sig&entitytype=song&
nameid=MN0000020585&include=review&format=xml&size=2
.
<?xml version="1.0" ?>
<playlistResponse xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="com.rovicorp.metadataservice" xmlns:meta="com.rovicorp.metadataservice" meta:id="tul1cpgpsrapp10:gwy:3hl8b2">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true" />
  </controlSet>
  <results>
    <result>
      <type>song</type>
      <relevance>
        <code>Score</code>
        <value>2.110506</value>
      </relevance>
      <availabilties xmlns="com.rovicorp.snrservice" />
      <id>MT0027313578</id>
      <messages i:nil="true" />
      <song>
        <ids>
          <amgClassicalTrackId i:nil="true" />
          <amgPopTrackId>T 1540209</amgPopTrackId>
          <isrcId>GBAJH0602656</isrcId>
          <muzeId>38607180</muzeId>
          <trackId>MT0027313578</trackId>
        </ids>
        <title>A Question of Lust</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000239921</id>
            <name>Depeche Mode</name>
          </AlbumArtist>
        </primaryArtists>
        <isPick>true</isPick>
        <genres>
          <Genre>
            <id>MA0000002572</id>
            <name>Electronic</name>
            <weight>7</weight>
          </Genre>
          <Genre>
            <id>MA0000002613</id>
            <name>Pop/Rock</name>
            <weight>7</weight>
          </Genre>
        </genres>
        <attributes i:nil="true" />
        <attributesUri i:nil="true" />
        <appearances i:nil="true" />
        <appearancesUri>http://api.rovicorp.com/data/v1.1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0027313578</appearancesUri>
        <moods i:nil="true" />
        <moodsUri>http://api.rovicorp.com/data/v1.1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0027313578</moodsUri>
        <review>
          <text>One of [roviLink="MN"]Martin Gore[/roviLink]'s most emotional ballads, [roviLink="MC"]"A Question of Lust"[/roviLink] is a tender yet epic slice of beauty. Whenever [roviLink="MN"]Gore[/roviLink] handles vocals on his own, it's a sign the song will deal with stark, personal feelings. Here, [roviLink="MN"]Gore[/roviLink]'s voice emerges as if he's singing a lullaby. By the time the song concludes, he's emoting desperation like a wounded gospel singer. Electronic sound effects build, tumble apart, and rebuild around his slightly echoing voice. Ambient sound washes, electronically processesed handclaps, complex racing keyboard melodies, and high-pitched synth notes paint an atmosphere of optimistic sadness. [roviLink="MN"]Gore[/roviLink] sings of all his weaknesses, from his fragility to his crippling inhibitions to his constant apologies. Each time he repeats the chorus, more emotion is revealed. "It's a question of lust/It's a question of trust/It's a question of not letting what we've built up crumble to dust," [roviLink="MN"]Gore[/roviLink] admits, that keep him and his lover together. [roviLink="MC"]"A Question of Lust"[/roviLink] is a vital cog, if not the heart, of [roviLink="MW"]Black Celebration[/roviLink]. It's a perfect [roviLink="MN"]Depeche Mode[/roviLink] song and one of [roviLink="MN"]Martin Gore[/roviLink]'s most touching artistic achievements. Despite the fact that he's pouring out his soul by nearly screaming his vocals at times, the song is as delicate as a baby's blanket. That he's still singing as [roviLink="MC"]"A Question of Lust"[/roviLink] fades out is all the more reason to reach for the repeat button on one's CD player. ~ Tim DiGravina</text>
          <author>Tim DiGravina</author>
        </review>
        <reviewUri>http://api.rovicorp.com/data/v1.1/song/review?format=xml&apikey=4p1k3y&trackId=MT0027313578</reviewUri>
        <styles i:nil="true" />
        <stylesUri>http://api.rovicorp.com/data/v1.1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0027313578</stylesUri>
        <themes i:nil="true" />
        <themesUri>http://api.rovicorp.com/data/v1.1/song/themes?format=xml&apikey=4p1k3y&trackId=MT0027313578</themesUri>
      </song>
    </result>
    <result>
      <type>song</type>
      <relevance>
        <code>Score</code>
        <value>1.5031029</value>
      </relevance>
      <availabilties xmlns="com.rovicorp.snrservice" />
      <id>MT0012004012</id>
      <messages i:nil="true" />
      <song>
        <ids>
          <amgClassicalTrackId i:nil="true" />
          <amgPopTrackId>T 1020731</amgPopTrackId>
          <isrcId>USEE10100558</isrcId>
          <muzeId i:nil="true" />
          <trackId>MT0012004012</trackId>
        </ids>
        <title>Magic</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000061172</id>
            <name>The Cars</name>
          </AlbumArtist>
        </primaryArtists>
        <isPick>true</isPick>
        <genres>
          <Genre>
            <id>MA0000002613</id>
            <name>Pop/Rock</name>
            <weight>7</weight>
          </Genre>
        </genres>
        <attributes i:nil="true" />
        <attributesUri i:nil="true" />
        <appearances i:nil="true" />
        <appearancesUri>http://api.rovicorp.com/data/v1.1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0012004012</appearancesUri>
        <moods i:nil="true" />
        <moodsUri>http://api.rovicorp.com/data/v1.1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0012004012</moodsUri>
        <review>
          <text>Although it sold zillions of copies, the word on 1984's [roviLink="MW"]Heartbeat City[/roviLink] by a lot of the [roviLink="MN"]Cars[/roviLink]' old-school fans was that it was too slick. Since the [roviLink="MN"]Cars[/roviLink] were always proudly, unapologetically slick, the argument doesn't really hold water. Perhaps what they mean -- especially in regards to the enormous hit [roviLink="MC"]"Magic,"[/roviLink] which was inescapable in the summer of 1984 -- is that the song is a bit slight and bubblegummy, and that [roviLink="MN"]Mutt Lange[/roviLink]'s production is exceedingly gimmicky. The song is certainly guilty on both counts, but in such a cavalier way that it seems bad form to get too worked up over deliberate silliness like the tongue-click sound that follows the first verse's line about high heels clicking or the way that the song's multiply-overdubbed, airy harmony vocals less-than-subtly recall [roviLink="MN"]Pilot[/roviLink]'s similarly cheesy 1975 hit [roviLink="MC"]"Magic"[/roviLink] on the "oh oh, it's magic" choruses. Even more than the downright goofy [roviLink="MC"]"You Might Think,"[/roviLink] [roviLink="MC"]"Magic"[/roviLink] is cotton candy for the ears, a giddy and possibly somewhat cynical bit of perfect pop radio fluff. ~ Stewart Mason</text>
          <author>Stewart Mason</author>
        </review>
        <reviewUri>http://api.rovicorp.com/data/v1.1/song/review?format=xml&apikey=4p1k3y&trackId=MT0012004012</reviewUri>
        <styles i:nil="true" />
        <stylesUri>http://api.rovicorp.com/data/v1.1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0012004012</stylesUri>
        <themes i:nil="true" />
        <themesUri>http://api.rovicorp.com/data/v1.1/song/themes?format=xml&apikey=4p1k3y&trackId=MT0012004012</themesUri>
      </song>
    </result>
  </results>
</playlistResponse>

Error Codes

CodeDescription
400 Incorrect or invalid request. The reason is shown in the Message object in ControlSet.

See Also

↑ Top

Personal tools