Descriptor/SignificantSongs
Returns the top songs in a musical genre or subgenre. By design, the list is limited to a maximum of 100 per genre or subgenre.
Syntax
descriptor/significantsongs?apikey=apikey&sig=sig&genreids=genreids [&format=format] [&offset=offset] [&count=count] [&country=country] [&language=language]
Request Example 1
- Request the top songs in the Country Blues and Contemporary Blues subgenres.
Request Example 2
- Request the top song in the Contemporary Blues subgenre.
Request Example 3
- Request the second top song in Contemporary Blues in an XML response.
Request Parameters
Click to re-sort
Parameter | Required | Description |
apikey | Yes | Access code that authorizes your request for data from Rovi. |
genreids | Yes | Genre ID or subgenre ID. You can get IDs of musical genres and subgenres from Descriptor/Genres or Descriptor/MusicGenres.
To specify multiple IDs, use a comma-separated list, like this: genreids=MA0000002467,MA0000002944. |
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. |
count | No | Number of items to be returned. The default is zero, which returns all items after the offset.
Use count and offset to paginate the response. |
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. |
language | No | Language of the response data. This request supports only en (English). |
offset | No | Number of items at the start of the returned list to skip. The default is zero.
Use count and offset to paginate the response. |
Response
Response | Type | Description |
build | String | The software release level of the API. |
code | Integer | HTTP status code. See the status field for the text part of the code. |
duration | Integer | Server processing time in milliseconds. The difference between startTime and endTime. |
endTime | String | When the server sent the response (UTC time). |
messages | Message [ ] | Elements of a multiple HTTP response status message. |
parameters | parameters | List of the parameters included in the request. |
serverName | String | Name of the server that processed the request. |
startTime | String | When the server received the request (UTC time). |
status | String | Text part of the HTTP status code that is shown in the code field. |
view | view | Summary of items returned in a list of items. |
Response for Descriptor/SignificantSongs
Response | Type | Description |
songs | SignificantSong [ ] | Top songs in the genres or subgenres specified in the request. |
JSON Response Example
- Here's the response to Request Example 2. It is formatted with extra spaces and carriage returns to make it easy to read.
{
"status":"ok",
"code":200,
"messages":null,
"build":"1.5.1.9",
"parameters":{
"apiKey":"apikey",
"id":"MA0000002960",
"offset":0,
"count":1
},
"view":{
"offset":0,
"count":1,
"total":49
},
"serverName":"tul1cssw3",
"startTime":"2011-04-29T00:18:02.3231228Z",
"endTime":"2011-04-29T00:18:02.3387481Z",
"duration":15,
"songs":[
{
"genre":{
"id":"MA0000002960",
"name":"Contemporary Blues"
},
"rank":109,
"id":"MT0001488586",
"title":"Am I Wrong",
"primaryArtists":[
{
"id":"MN0000370703",
"name":"Keb' Mo'"
}
],
"album":{
"id":"MW0000114898",
"title":"Keb' Mo'",
"year":"1994-06-03",
"thumbnail":{
"sm_75":"http:\/\/actual-url-concealed.jpg",
"md_170":"http:\/\/actual-url-concealed.jpg",
"lg_250":"http:\/\/actual-url-concealed.jpg"
}
}
}
]
}
XML Response Example
- Here's the response to Request Example 3.
<SignificantSongs xmlns="com.rovicorp.metadataservice" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<status>ok</status>
<code>200</code>
<messages i:nil="true"/>
<build>1.5.1.9</build>
<parameters>
<apiKey>apikey</apiKey>
<id>MA0000002960</id>
<offset>1</offset>
<count>1</count>
<format>xml</format>
</parameters>
<view>
<offset>1</offset>
<count>1</count>
<total>49</total>
</view>
<serverName>tul1cssw3</serverName>
<startTime>2011-04-29T00:17:24.5723980Z</startTime>
<endTime>2011-04-29T00:17:24.6192739Z</endTime>
<duration>46</duration>
<songs>
<SignificantSong>
<genre>
<id>MA0000002960</id>
<name>Contemporary Blues</name>
</genre>
<rank>109</rank>
<id>MT0001200929</id>
<title>Drop Down Mama</title>
<primaryArtists>
<AlbumArtist>
<id>MN0001486767</id>
<name>John Hammond, Jr.</name>
</AlbumArtist>
</primaryArtists>
<album>
<id>MW0000615761</id>
<title>The Best of John Hammond</title>
<year>1989-??-??</year>
<thumbnail>
<sm_75>http://actual-url-concealed.jpg</sm_75>
<md_170>http://actual-url-concealed.jpg</md_170>
<lg_250>http://actual-url-concealed.jpg</lg_250>
</thumbnail>
</album>
</SignificantSong>
</songs>
</SignificantSongs>
See Also
↑ Top