Advanced Personal Playlist
This request offers insight into some of the custom capabilities available from Rovi Advanced Recommendations. This is one of several requests that show how Rovi can generate entertainment recommendations for your customers. To understand this feature, we suggest working with these calls in this order:
| This Request . . . | Demonstrates . . . |
|
|
How an item taste profile gets added to a user taste profile.
What an item taste profile looks like.
What a user taste profile looks like.
How personalized recommendations are generated from a user taste profile.
How personalized song playlists are generated from a user taste profile.
|
Advanced Personal Playlist returns a playlist of songs based on either a user taste profile or a seed item, which can be a song, album, artist, or any of hundreds of music attributes. This request can generate truly personalized song playlists based on user actions or opinions about music that were recorded with the Event request, as well as playlists based on music or a music attribute that a user likes.
The hundreds of music attributes you can use to seed a playlist include the following:
| hundreds of styles such as goth rock, smooth soul, and progressive bluegrass. |
| hundreds of moods such as bittersweet, cosmopolitan, and meditative. |
| dozens of themes such as family, goodbyes, and road trip. |
| dozens of genres such as rap, holiday, and classical. |
| hundreds of subgenres such as salsa, musique concrète, and contemporary blues. |
Playlist randomizes results within the criteria you specify, so repeated requests return different results and different sequences of results. 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.
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? |
userid=userid
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 25 songs based on the taste profile of user ID 100.
Request Example 2
- Request a playlist of 15 songs based on the Adult Contemporary R&B subgenre and include a sample of each song.
Request Example 3
- Request a playlist based on the taste profile of user ID 100 with at least four songs between songs on the same album and no more than three songs on the same album.
Request Example 4
- 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 5
- Request a playlist based on the Broken Water song Drown in an XML response.
Request Example 6
- Request a playlist based on the singer Terri Nunn and include any reviews available.
Request Parameters
| Parameter | Required | Description |
|---|
| 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. For a request with an album ID, specify an endpoint of music. Here are some album IDs you can use for evaluation tests:
- MW0002136254 — 4 (Beyoncé)
- MW0000056882 — Thriller (Michael Jackson)
- MW0000111184 — Birth of the Cool (Miles Davis)
- MW0001946960 — Beethoven: Symphony 9 (Leonard Bernstein)
Condition: The request must contain just one of these parameters:
- userid
- nameid
- albumid
- trackid
- attributeid
|
| attributeid | Conditional | Rovi ID for a music mood, style, theme, genre, or subgenre, consisting of the prefix MA or XA followed by a ten-digit number, specified like this: attributeid=MA0000002504 or attributeid=XA0000001029. Here are some attribute IDs you can use for evaluation tests:
- MA0000002592 — Folk music genre
- MA0000002461 — Big band music subgenre
- MA0000012258 — Techno Bass music style
- MA0000005051 — Dance party music theme
- MA0000006285 — Halloween music theme
- XA0000001022 — Hymn-like music mood
- XA0000000776 — Thrilling music mood
Condition: The request must contain just one of these parameters:
- userid
- nameid
- albumid
- trackid
- attributeid
|
| nameid | Conditional | Rovi Name ID for a person or group that has worked in music, consisting of the prefix MN followed by a ten-digit number. For a request with a name ID, specify an endpoint of music. Here are some name IDs you can use for evaluation tests:
- MN0000775877 — Coldplay
- MN0000994823 — Lady Gaga
- MN0000187478 — Eric Clapton
- MN0000239859 — Leonard Bernstein
Condition: The request must contain just one of these parameters:
- userid
- nameid
- albumid
- trackid
- attributeid
|
| trackid | Conditional | Rovi Music ID for a song, consisting of the prefix MT followed by a ten-digit number. For a request with a track ID, specify an endpoint of music. Here are some track IDs you can use for evaluation tests:
- MT0000136981 — Speed of Sound (Coldplay)
- MT0040645959 — Born This Way (Lady Gaga)
- MT0000149626 — Billie Jean (Michael Jackson)
- MT0041013551 — Concierto de Aranjuez (Miles Davis)
Condition: The request must contain just one of these parameters:
- userid
- nameid
- albumid
- trackid
- attributeid
|
| userid | Conditional | ID of a user for whom events have been previously submitted for the music endpoint.
Condition: The request must contain just one of these parameters:
- userid
- 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 | Type | Description |
|---|
| controlSet | ControlSet | The HTTP response status. |
| meta:id | string | Server transaction ID for the response. |
Response for Advanced Personal Playlist
| Response | Type | Description |
|---|
| results | result [ ] | Information about items that are similar to the items specified in the request. |
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/snrpreview/v2.1/music/playlist?apikey=apikey&sig=sig&
entitytype=song&attributeid=MA0000006310&include=sample&format=json&size=1.
{
"playlistResponse":{
"meta:id":"tul1cpgssrapp1:gwy:36cqb",
"controlSet":{
"status":"ok",
"code":200,
"messages":null
},
"results":[
{
"type":"song",
"relevance":[
{
"code":"Score",
"value":0.810014
}
],
"id":"MT0003427225",
"messages":null,
"song":{
"ids":{
"amgClassicalTrackId":null,
"amgPopTrackId":"T 7250756",
"isrcId":null,
"muzeId":"8687401",
"trackId":"MT0003427225"
},
"title":"Uncle Pen",
"primaryArtists":[
{
"id":"MN0000735310",
"name":"Bill Monroe & His Bluegrass Boys"
},
{
"id":"MN0000081083",
"name":"Bill Monroe"
}
],
"isPick":true,
"genres":[
{
"id":"MA0000002532",
"name":"Country",
"weight":9
}
],
"appearances":null,
"appearancesUri":"http://api.rovicorp.com/data/v1.1/song/appearances?format=json&apikey=4p1k3y&trackId=MT0003427225",
"moods":null,
"moodsUri":"http://api.rovicorp.com/data/v1.1/song/moods?format=json&apikey=4p1k3y&trackId=MT0003427225",
"review":null,
"reviewUri":null,
"styles":null,
"stylesUri":"http://api.rovicorp.com/data/v1.1/song/styles?format=json&apikey=4p1k3y&trackId=MT0003427225",
"themes":null,
"themesUri":"http://api.rovicorp.com/data/v1.1/song/themes?format=json&apikey=4p1k3y&trackId=MT0003427225",
"sample":"http://actual-url-concealed.mp3",
"sampleUri":"http://api.rovicorp.com/data/v1.1/song/sample?format=json&apikey=4p1k3y&trackId=MT0003427225"
}
}
]
}
}
XML Response Example
- A top response to the request for a playlist based on the singer Terri Nunn along with any reviews available.
- Requested with http://api.rovicorp.com/snrpreview/v2.1/music/playlist?apikey=apikey&sig=sig&
entitytype=song&nameid=MN0000020585&include=review&format=xml&size=1.
<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="tul1cpgssrapp1:gwy:36clr">
<controlSet>
<status>ok</status>
<code>200</code>
<messages i:nil="true"/>
</controlSet>
<results>
<result>
<type>song</type>
<relevance>
<code>Score</code>
<value>2.1093132</value>
</relevance>
<id>MT0027090491</id>
<messages i:nil="true"/>
<song>
<ids>
<amgClassicalTrackId i:nil="true"/>
<amgPopTrackId>T 207139</amgPopTrackId>
<isrcId i:nil="true"/>
<muzeId i:nil="true"/>
<trackId>MT0027090491</trackId>
</ids>
<title>Black Celebration</title>
<primaryArtists>
<AlbumArtist>
<id>MN0000239921</id>
<name>Depeche Mode</name>
</AlbumArtist>
</primaryArtists>
<isPick>true</isPick>
<genres>
<Genre>
<id>MA0000002613</id>
<name>Pop/Rock</name>
<weight>9</weight>
</Genre>
<Genre>
<id>MA0000002572</id>
<name>Electronic</name>
<weight>6</weight>
</Genre>
</genres>
<appearances i:nil="true"/>
<appearancesUri>http://api.rovicorp.com/data/v1.1/song/appearances?format=xml&apikey=4p1k3y&trackId=MT0027090491</appearancesUri>
<moods i:nil="true"/>
<moodsUri>http://api.rovicorp.com/data/v1.1/song/moods?format=xml&apikey=4p1k3y&trackId=MT0027090491</moodsUri>
<review>
<text>After [roviLink="MC"]"Blasphemous Rumours,"[/roviLink] could [roviLink="MN"]Depeche Mode[/roviLink] really turn back from the dark trajectory on which they'd embarked? [roviLink="MC"]"Black Celebration,"[/roviLink] the opening track to the album which shares its title, is a [muzeItalic]celebration[/muzeItalic] of the band's somewhat new, fiercely gloomy embrace of darkness. The musical arrangement is an ode to edginess: icy, piercing synths that build from what sounds like the minimal score to a horror film into what might pass for theme music for a nocturnal gathering of goblins. Indeed, in the slow racing tones that begin the song, one hears many similarities to [roviLink="MN"]Dario Argento[/roviLink] collaborators [roviLink="MN"]Goblin[/roviLink] and [roviLink="MN"]John Carpenter[/roviLink]'s score for [roviLink="VW"]Halloween[/roviLink]. Simmering background sound effects suggest the growl or howl of nightmarish creatures. A dance beat arises, but with the increasingly chilly synths sucking away optimism, the song doesn't necessarily signal a stampede to the dance floor. [roviLink="MN"]David Gahan[/roviLink]'s tremulous, echoing, and processed voice is no brighter than the keyboard foundation it rises over. [roviLink="MN"]Martin Gore[/roviLink] steps in with background vocals, eager to add a sinister, spooky punctuation to drive his lyrics home. That [roviLink="MC"]"Black Celebration"[/roviLink] is actually a love song is quite remarkable. Looking past [roviLink="MN"]Gahan[/roviLink]'s cries that there's been another "black day," he's calling to his lover that he wants to take him or her "in his arms" to find consolation and relief. Why not celebrate their mutual disgust with the world? Why not revel in the reality that things aren't getting better? It's hard to imagine a more perfect opening to the band's fifth album and second foray into the shadows than [roviLink="MC"]"Black Celebration."[/roviLink] ~ Tim DiGravina</text>
<author>Tim DiGravina</author>
</review>
<reviewUri>http://api.rovicorp.com/data/v1.1/song/review?format=xml&apikey=4p1k3y&trackId=MT0027090491</reviewUri>
<styles i:nil="true"/>
<stylesUri>http://api.rovicorp.com/data/v1.1/song/styles?format=xml&apikey=4p1k3y&trackId=MT0027090491</stylesUri>
<themes i:nil="true"/>
<themesUri i:nil="true"/>
<sample i:nil="true"/>
<sampleUri>http://api.rovicorp.com/data/v1.1/song/sample?format=xml&apikey=4p1k3y&trackId=MT0027090491</sampleUri>
</song>
</result>
</results>
</playlistResponse>
Error Codes
| Code | Description |
|---|
| 400 | Incorrect or invalid request. The reason is shown in the Message object in ControlSet. |
See Also
-
↑ Top