V1.Metadata.MusicService.Album:Info

Jump to: navigation, search

Album/Info

Returns basic information about an album plus customized requests for the other Album content that is available. These customized requests are designed to make your programming easy and efficient: in a single step you both verify availability of data and capture the request. You just add the sig parameter and execute the request.

The album/info request also provides an optional argument to include responses from any or all of the other Album requests. This may return a large amount of data. To speed data transmission, do the following:

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

If an album has multiple releases, the Album response presents information from the main release of the album. The difference between Album and Release information is that only Release returns the list of performances on a classical music release and only Album returns similar albums and the original release date.

Syntax

album/info? album=album
albumid=albumid
amgpopid=amgpopid
amgclassicalid=amgclassicalid 		&apikey=apikey&sig=sig [&include=include] [&format=format] [&country=country] [&language=language]

Request Example 1

Request information about the album Double Live.
http://api.rovicorp.com/data/v1/album/info?apikey=apikey&sig=sig&album=double%20live

Request Example 2

Request information about the album Double Live using an album ID.
http://api.rovicorp.com/data/v1/album/info?apikey=apikey&sig=sig&albumid=MW0000043068

Request Example 3

Also request the lists of tracks and releases.
http://api.rovicorp.com/data/v1/album/info?apikey=apikey&sig=sig&albumid=MW0000043068&
include=tracks,releases

Request Example 4

Request information using an AMG Pop ID for an existing application that uses legacy AMG IDs.
http://api.rovicorp.com/data/v1/album/info?apikey=apikey&sig=sig&amgpopid=R+++381778

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikey Yes Access code that authorizes your request for data from Rovi.
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.

album Conditional Keywords from the album title. This searches for the most popular title with that combination of words. Replace spaces with plus (+) or percent20 (%20) symbols.

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

  • album
  • albumid
  • amgpopid
  • amgclassicalid
albumid Conditional Rovi Music ID for an album, consisting of the prefix MW followed by a ten-digit number. For example: MW0000056882. You can grab album IDs from responses to the following requests:

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

  • album
  • albumid
  • amgpopid
  • amgclassicalid
amgclassicalid Conditional All Media Guide (AMG) ID for a classical music album, consisting of a ten-character string that starts with W and is followed by nine digits with leading spaces. For example: W   180317. When using an AMG Classical ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: W+++180317. AMG is a legacy database of entertainment information.

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

  • album
  • albumid
  • amgpopid
  • amgclassicalid
amgpopid Conditional All Media Guide (AMG) ID for a popular music album, consisting of a ten-character string that starts with R and is followed by nine digits with leading spaces. For example: R  1805889. When using an AMG Pop ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: R++1805889.

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

  • album
  • albumid
  • amgpopid
  • amgclassicalid
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.
include No Other Album requests to include in the request. To include images of the main album release in the response, for example, add include=images. For multiple includes, separate the values with commas like this: include=images,tracks. You can also include all Album requests with include=all. The possible values are:

For information about a request, please see the documentation for the request.

Notice: The value Similar is deprecated and will be removed from the API on a date to be announced.

Reminder: These options may return a large amount of data. To speed data transmission, do the following:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
language No Language of the response. This request supports only en, English.

Response

Response Header

ResponseTypeDescription
buildStringThe software release level of the API.
codeIntegerHTTP status code. See the status field for the text part of the code.
durationIntegerServer processing time in milliseconds. The difference between startTime and endTime.
endTimeStringWhen the server sent the response (UTC time).
messagesMessage [ ]Elements of a multiple HTTP response status message.
parametersparametersList of the parameters included in the request.
serverNameStringName of the server that processed the request.
startTimeStringWhen the server received the request (UTC time).
statusStringText part of the HTTP status code that is shown in the code field.

Response for Album/Info

ResponseTypeDescription
classicalReview classicalReview An editorial review of a classical music album, returned only if the request specified an include=classicalreview argument.
classicalReviewUri String The customized Album/ClassicalReview request, returned only if the data is available.
credits AlbumCredit [ ] Production credits for the album, returned only if the request specified an include=credits argument.
creditsUri String The customized Album/Credits request, returned only if the data is available.
duration Integer Playing time in seconds.
flags String [ ] Additional features and characteristics that apply to the album:
  • 24-Bit Mastered
  • Arrangement
  • Bootleg
  • Cast Recording
  • Christmas
  • Collectors Edition
  • Compilation
  • Digitally Remastered
  • DJ Mix
  • Exercise
  • Expurgated Version
  • Gold
  • HDCD Mastered
  • Highlights
  • Holiday
  • Instrumental
  • International Version
  • Interview
  • Karaoke
  • Limited Edition
  • Offensive image,title,lyrics
  • Religious
  • Remixes
  • Slow
  • Soundtrack
  • Tribute
  • Video
  • XRCD Mastered
genres Genre [ ] Musical genres the album falls into, along with a weighting that reflects the relative importance of each genre.
guestArtists AlbumArtist [ ] Names of guest artists that appear on the album.
headlineReview headlineReview A capsule review that sums up the critical and historical perspective of the album in one or two sentences.
ids ids All of the IDs that are recognized by the API for an album. The possible IDs are:
  • albumId
  • amgPopId
  • amgClassicalId
images images URLs to images of the front and back album covers, returned only if the request specified an include=images argument and your subscription level enables access to images. Note: Photography credits must be displayed with images.
imagesUri String The customized Album/Images request, returned only if the data is available.
isPick Boolean Whether the album is recommended by Rovi: true or false.
moods Mood [ ] Terms that describe expressive characteristics of the music, returned only if the request specified an include=moods argument.
moodsUri String The customized Album/Moods request, returned only if the data is available.
originalReleaseDate String Date of the first release of the album in YYYY-MM-DD format.
primaryArtists AlbumArtist [ ] Names of the primary artists on the album.
primaryReview primaryReview The most recent major review of the album, returned only if the request specified an include=primaryreview argument.
primaryReviewUri String The customized Album/PrimaryReview request, returned only if the data is available.
rating Integer An editorially assigned rating of the album from 0 to 10, where 0 is no rating and higher numbers indicate a higher rating.
releases AlbumRelease [ ] List of the album releases, returned only if the request specified an include=releases argument.
releasesUri String The customized Album/Releases request, returned only if the data is available.
similar AlbumSimilar [ ] Similar albums to the album named in the request, returned only if the request specified an include=similar argument.

Notice: This property is deprecated and will be removed from the API on a date to be announced.

similarUri String The customized Album/Similar request, returned only if the data is available.

Notice: This property is deprecated and will be removed from the API on a date to be announced.

styles Style [ ] Musical styles relevant to the music on the album, returned only if the request specified an include=styles argument.
stylesUri String The customized Album/Styles request, returned only if the data is available.
themes Theme [ ] Topics, feelings, and circumstances that motivate or fit with the music, returned only if the request specified an include=themes argument.
themesUri String The customized Album/Themes request, returned only if the data is available.
title String Full name of the album.
tracks Track [ ] List of tracks on the album, returned only if the request specified an include=tracks argument.
tracksUri String The customized Album/Tracks request, returned only if the data is available.

JSON Response Example

Here's the response to Request Example 1. 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":"double live"
  },
  "serverName":"tul1cssw4",
  "startTime":"2011-04-27T18:49:45.3417571Z",
  "endTime":"2011-04-27T18:49:45.4042575Z",
  "duration":62,
  "album":{
    "ids":{
      "albumId":"MW0000043068",
      "amgClassicalId":null,
      "amgPopId":"R  381778"
    },
    "title":"Double Live",
    "primaryArtists":[
      {
        "id":"MN0000798248",
        "name":"Garth Brooks"
      }
    ],
    "guestArtists":[
      {
        "id":"MN0000032333",
        "name":"Susan Ashton"
      },
      {
        "id":"MN0000804642",
        "name":"Ty England"
      },
      {
        "id":"MN0000151290",
        "name":"Béla Fleck"
      },
      {
        "id":"MN0000044751",
        "name":"Steve Wariner"
      },
      {
        "id":"MN0000749476",
        "name":"Trisha Yearwood"
      }
    ],
    "flags":null,
    "duration":6047,
    "originalReleaseDate":"1998-11-17",
    "rating":4,
    "isPick":false,
    "genres":[
      {
        "id":"MA0000002532",
        "name":"Country",
        "weight":10
      }
    ],
    "headlineReview":null,
    "classicalReview":null,
    "classicalReviewUri":null,
    "credits":null,
    "creditsUri":"http:\/\/api.rovicorp.com\/v1\/album\/credits?format=json&apikey=apikey&albumid=MW0000043068",
    "images":null,
    "imagesUri":"http:\/\/api.rovicorp.com\/v1\/album\/images?format=json&apikey=apikey&albumid=MW0000043068",
    "moods":null,
    "moodsUri":"http:\/\/api.rovicorp.com\/v1\/album\/moods?format=json&apikey=apikey&albumid=MW0000043068",
    "primaryReview":null,
    "primaryReviewUri":"http:\/\/api.rovicorp.com\/v1\/album\/primaryReview?format=json&apikey=apikey&albumid=MW0000043068",
    "releases":null,
    "releasesUri":"http:\/\/api.rovicorp.com\/v1\/album\/releases?format=json&apikey=apikey&albumid=MW0000043068",
    "similar":null,
    "similarUri":"http:\/\/api.rovicorp.com\/v1\/album\/similar?format=json&apikey=apikey&albumid=MW0000043068",
    "styles":null,
    "stylesUri":"http:\/\/api.rovicorp.com\/v1\/album\/styles?format=json&apikey=apikey&albumid=MW0000043068",
    "themes":null,
    "themesUri":"http:\/\/api.rovicorp.com\/v1\/album\/themes?format=json&apikey=apikey&albumid=MW0000043068",
    "tracks":null,
    "tracksUri":"http:\/\/api.rovicorp.com\/v1\/album\/tracks?format=json&apikey=apikey&albumid=MW0000043068"
  }
}

XML Response Example

Here's the XML response to Request Example 1.
<AlbumDetail 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>double live</id>
    <format>xml</format>
  </parameters>
  <serverName>tul1cssw4</serverName>
  <startTime>2011-04-27T20:20:23.4343532Z</startTime>
  <endTime>2011-04-27T20:20:23.4343532Z</endTime>
  <duration>0</duration>
  <album>
    <ids>
      <albumId>MW0000043068</albumId>
      <amgClassicalId i:nil="true"/>
      <amgPopId>R 381778</amgPopId>
    </ids>
    <title>Double Live</title>
    <primaryArtists>
      <AlbumArtist>
        <id>MN0000798248</id>
        <name>Garth Brooks</name>
      </AlbumArtist>
    </primaryArtists>
    <guestArtists>
      <AlbumArtist>
        <id>MN0000032333</id>
        <name>Susan Ashton</name>
      </AlbumArtist>
      <AlbumArtist>
        <id>MN0000804642</id>
        <name>Ty England</name>
      </AlbumArtist>
      <AlbumArtist>
        <id>MN0000151290</id>
        <name>Béla Fleck</name>
      </AlbumArtist>
      <AlbumArtist>
        <id>MN0000044751</id>
        <name>Steve Wariner</name>
      </AlbumArtist>
      <AlbumArtist>
        <id>MN0000749476</id>
        <name>Trisha Yearwood</name>
      </AlbumArtist>
    </guestArtists>
    <flags xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true"/>
    <duration>6047</duration>
    <originalReleaseDate>1998-11-17</originalReleaseDate>
    <rating>4</rating>
    <isPick>false</isPick>
    <genres>
      <Genre>
        <id>MA0000002532</id>
        <name>Country</name>
        <weight>10</weight>
      </Genre>
    </genres>
    <headlineReview i:nil="true"/>
    <classicalReview i:nil="true"/>
    <classicalReviewUri i:nil="true"/>
    <credits i:nil="true"/>
    <creditsUri>http://api.rovicorp.com/v1/album/credits?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</creditsUri>
    <images i:nil="true"/>
    <imagesUri>http://api.rovicorp.com/v1/album/images?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</imagesUri>
    <moods i:nil="true"/>
    <moodsUri>http://api.rovicorp.com/v1/album/moods?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</moodsUri>
    <primaryReview i:nil="true"/>
    <primaryReviewUri>http://api.rovicorp.com/v1/album/primaryReview?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</primaryReviewUri>
    <releases i:nil="true"/>
    <releasesUri>http://api.rovicorp.com/v1/album/releases?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</releasesUri>
    <similar i:nil="true"/>
    <similarUri>http://api.rovicorp.com/v1/album/similar?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</similarUri>
    <styles i:nil="true"/>
    <stylesUri>http://api.rovicorp.com/v1/album/styles?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</stylesUri>
    <themes i:nil="true"/>
    <themesUri>http://api.rovicorp.com/v1/album/themes?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</themesUri>
    <tracks i:nil="true"/>
    <tracksUri>http://api.rovicorp.com/v1/album/tracks?format=xml&amp;apikey=apikey&amp;albumid=MW0000043068</tracksUri>
  </album>
</AlbumDetail>


See Also

↑ Top

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/V1.Metadata.MusicService.Album:Info"
Personal tools