Overview of Rovi Music
Rovi Music gives you access to one of the most comprehensive catalogues of music data, images, and samples in the world. This is the database that powers AOL, iTunes, Yahoo, BestBuy, Midomi, Qsonix, Pandora, Slacker and others. Take advantage of it. Create a compelling entertainment experience or application that draws consumers to your device, service, or website. And include the other services in Rovi Cloud Services that fit your vision.
The database that powers Rovi Music has a storied heritage. It was started by musicians, filmmakers, and media geeks at a time when it wasn't certain there would be a demand for a service that would help people find and learn about entertainment they would like. But it became an obsession. We had to do it. And we didn't want to be like other "experts." We didn't want to tell people what their taste should be or rate artists against each other. We wanted to rank music under objective, relevant criteria—moods, themes, styles, genres, and subgenres—and we wanted to describe and review music within the context of the genres and subgenres it falls in. And that vision fuels us to this day. That is in our DNA.
Rovi Music is designed by musicologists and software architects for music fans who also happen to be application developers. The documentation assumes you understand the following:
- The basic concepts of XML, JSON, HTTP, and REST.
- The development environment and language you are using.
- How to compose HTTP requests and parse XML or JSON responses.
- Rovi Music is composed of three APIs:
|Music API|| The Music API delivers music data, audio samples, and album images.
|Name API || The Name API delivers data about the people, groups, and organizations that have contributed to music, and it points you to the music they contributed to. It also covers people in movies and television so you can provide a seamless connection to artists’ work in movies and television if you also use Rovi DVD and Rovi Video.
|Descriptor API || The Descriptor API lists and defines the musical styles and genres used in the Music API and points you to the most significant music in each genre.
The Music API
- The Music API accesses five interlaced collections of music data:
| Song || About a song recording. Includes a link to an audio sample.
| Album || About an album, in particular the main release of the album. Includes links to images and audio samples.
| Release || About an album release. An album may be released in different formats and with different features over the years. The difference between Album and Release 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.
| Performance || About a classical music performance. Includes links to images.
| Composition || About a classical music composition. A composition can include multiple parts or movements, each of which is each recorded as a single track. A variety of compositions may be performed on a classical music album.
The Name API
- The Name API accesses an exhaustive database of information about people, groups, and organizations involved in music. For these people, the Name API:
- Provides their credits, images, and biographies.
- Identifies the moods, themes, and musical styles associated with them.
- Lists collaborators, contemporaries, people they influenced, and people who influenced them.
- Points you to their songs, albums, and compositions, and to video previews associated with them.
The Descriptor API
- The Descriptor API focuses on musical styles and genres. The Descriptor API:
- Provides descriptions of the musical styles and genres.
- Identifies the most significant artists and composers in a musical genre.
- Reveals the most significant songs, albums, and compositions in a musical genre.
- Rovi Music data features:
- Constantly updated, always current, always relevant.
- Subjected to rigorous copy proofing and data integrity best practices.
- Original editorial content, including reviews, fact sheets, descriptions, and biographies.
- Objective, relevant classification criteria based on hundreds of moods, themes, styles, genres, and subgenres.
- Optimized for multiple platforms and devices so you can provide a high-quality and consistent experience across all devices.
- Rovi Cloud Services platform features:
- CDN-based hosting and delivery of rich media content.
- Industry standard technologies deliver scalability, security, and operational reliability.
- High performance, distributed caching architecture for fast and efficient data retrieval.
- Hosted in redundant data centers in multiple locations around the world, supporting millions of devices and applications.
- To receive data from Rovi Music, your website or application sends HTTP requests to the Rovi API server, and the API server responds with the data in standard XML or JSON format. The Rovi API server is stateless, treating each request as an isolated transaction and unrelated to any other transaction. Requests do not require a login, logout, or any other session management.
- The Rovi API server expects standard HTTP/1.1 requests with UTF-8 character encoding. Characters, except for those in the unreserved set, should be percent encoded (also called URL encoded). A space, however, can be represented as either a plus (+) or as %20.
- Here is a sample API request which asks for information about the album Birth of the Cool, including images that are in the range of 60 to 80 pixels in both dimensions.
- Elements shown in boldface are case-sensitive.
- Requests consist of the host URL, path segments, and a query string.
- Arguments in the query string are:
- Specified in the parameter=value format.
- Two of the arguments in the query string authorize your access to the API and are required in every request:
- An API key. You can request your free API key here.
- A signature. The signature is a time-sensitive calculated value.
- The following table describes the purposes of the elements of the sample request:
|http://api.rovicorp.com||No||The host URL.|
|/data||Yes||The service requested.|
|/v1.1||Yes||The version of the service, consisting of the letter v plus the version number.|
|/album||Yes||The function called.|
|/info||No||The function request called.|
|albumid=MW0000111184||No||Parameter to pass to the function request and the value assigned to the parameter.|
|include=images||No||Parameter to pass to the function request and the value assigned to the parameter.|
|imagesize=60-80x60-80||No||Parameter to pass to the function request and the value assigned to the parameter.|
|apikey=abcd1efghi23jklmnopq45rs6||No||API key that authorizes your use of the API.|
|sig=149522a6c3c3fee7ea629493e767ac68||Yes||Authentication signature you calculate just before sending the request.|
How to Calculate the Authentication Signature for the Request
- As mentioned above, two arguments in the query authenticate your access to the API server, the apikey=apikey and sig=sig arguments. The sig=sig argument passes a calculated value.
- To calculate the value, 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. A five-minute wiggle is permitted on either side of the current timestamp to allow for clock drift.
- Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time.
- Here are links to code samples to get you started:
Request Compressed Data for a Faster Response
- We strongly recommend that you take advantage of receiving Rovi Cloud Services data in compressed format. The size of compressed data is typically less than 50 percent of uncompressed data, and as a result your apps use that much less bandwidth and receive data that much faster.
- Rovi transmits compressed data in gzip format.
- To receive compressed data, you just need to add an Accept-Encoding header field with each request, like this:
- Accept-Encoding: gzip,deflate
- When you receive the response, you can verify that the data is compressed by checking the response headers. The response header Content-Encoding: gzip indicates that the message body contains compressed data. To decompress the response data, use the Deflate data compression algorithm, which is available in most languages.
- Rovi API servers generate an HTTP 1.1 response to each request they receive. A response contains HTTP response headers, which define operating parameters of the response, followed by the message body in one of the following formats:
- XML-formatted data.
- JSON-formatted data.
- If your contract with Rovi permits caching of Rovi data, you need to decide how to control the duration of cached data, that is, how long you return cached data before you need to refresh it. There are a couple of ways to do that: 1) by using the Cache-Control header fields returned in responses, and 2) by adjusting configuration settings in your cache software.
- However you control the duration of cached data, the duration must meet the terms of your contract with Rovi. Cache-Control headers in a response do not authorize caching of Rovi data and do not authorize caching beyond the time allowed by your contract. The purpose of Cache-Control header fields is to give you a ready guideline for your caching. We modify these header values over time as we update our caching algorithms, and we reserve the right to do that at any time. Our caching guidelines are intended to give you the best certainty that you have the most current data available.
- For further guidelines about caching Rovi data, please see Caching Best Practices.
- Note: Caching of Rovi data is specifically prohibited unless contractually authorized. If you would like to cache Rovi data for your application, please contact your customer service representative about obtaining authorization.
- The HTTP response headers that provide directives for caching are described in the following table:
|Cache-Control: max-age=||Number of seconds remaining until more recent data may be available from this request. When that time has elapsed, your cache needs to perform a new request to Rovi Cloud Services for that data before the cache fulfills additional requests for that data.|
|Cache-Control: must-revalidate ||Tells your cache that it must refresh response data with the Rovi API server, and not an intermediate cache, after data expires and before it fulfills additional requests for the data.|
|Last-Modified:||The last time the data in the response changed, specified as GMT.|
|Expires:||When more recent data may be available, specified as GMT. A new request for data from Rovi Cloud Services should be performed after that time and before the cache fulfills addtional requests for that data. However, if a value is also provided in the Cache-Control: max-age header, the Expires header should be ignored, and the value provided with the Cache-Control: max-age header should be used instead.|
Types of Response
- There are three types of responses you need to code for:
- Expected responses. Normal responses should be processed as follows:
- Parse the data.
- Present the data on your device, website, or application.
- Use URLs and database IDs in the data to make other requests.
- Responses with unavailable data. Your code should allow for missing data after the HTTP header and after a response field. Unavailable data may appear as follows:
- No characters.
- An empty string.
- The word null after a response field.
- Error codes, which are returned as HTTP status codes in the response header.
URLs in the Response Data
- Some requests return URLs in response data. These URLs are preformatted HTTP requests for other content, and to use them you just copy them, append the required signature parameter, and execute the call.
URLs in Info Requests
- The info requests return preformatted URLs of requests that have content available. These URLs are designed to make your programming easy and efficient: in a single step you both verify availability of the data and you capture the request.
- For example, in the following portion of an info response you'll notice that there is no preformatted request URL for the classicalReviewUri element. When parsing this response, you know a classical review is inapplicable or unavailable, so you know not to offer that information. On the other hand, you know there is data available for creditsUri, imagesUri, moodsUri, etc.
URLs to Images and Audio Samples
- To decrease response time, requests for images and audio samples return URLs to the images and audio samples. Design your application to either automatically execute those URLs or provide icons so your customers can execute them.
- Note: Access to images and audio samples is governed by your subscription level and geographical location.
Tags in Text Responses
- Text data in responses commonly contain HTML tags or Rovi hyperlink tags. You can use the HTML tags to format the text, and you can use the hyperlink tags to create hyperlinks to other pages.
HTML Tags in Text Responses
- Factsheets may contain HTML tags for unordered lists and italics. You can drop these responses straight into web pages. Here's a sample response:
<LI>Began playing the piano at 10 and was among the first group of students to attend the summer music academy Berkshire Music Center.
<LI>Was only 25 when he conducted his first matinee with the New York Philharmonic, filling in for a sick maestro. He would go on to conduct over 900 concerts with the NYP, more than any conductor in its history at the time.
<LI>In 1937, published his first piece on writing music in Modern Music Magazine.
<LI>Was credited with bringing music to the masses through his annually televised <I>Young People's Concerts</I> on CBS.
<LI>In 1989, he refused the National Medal of Arts award from President George W. Bush. Known for his political activism, he was protesting the revocation of grant money in connection with an AIDS-related art exhibit.
<LI>Was diagnosed with emphysema in his mid-twenties. Announced his retirement from the concert stage just six days before his death from complications from the disease and mesothelioma.</LI></UL>
- Dropped into a web page, the above text looks like this:
- Began playing the piano at 10 and was among the first group of students to attend the summer music academy Berkshire Music Center.
- Was only 25 when he conducted his first matinee with the New York Philharmonic, filling in for a sick maestro. He would go on to conduct over 900 concerts with the NYP, more than any conductor in its history at the time.
- In 1937, published his first piece on writing music in Modern Music Magazine.
- Was credited with bringing music to the masses through his annually televised Young People's Concerts on CBS.
- In 1989, he refused the National Medal of Arts award from President George W. Bush. Known for his political activism, he was protesting the revocation of grant money in connection with an AIDS-related art exhibit.
- Was diagnosed with emphysema in his mid-twenties. Announced his retirement from the concert stage just six days before his death from complications from the disease and mesothelioma.
Rovi Hyperlink Tags in Text Responses
- Reviews, biographies, and descriptions returned in responses commonly contain tags you can use to create hyperlinks to other pages. Tags are structured like XML elements, but are enclosed in square brackets instead of angle brackets. Here's a sample sentence with several tags:
After a two-month trial, he was found guilty, depleting the band financially and mentally and nearly causing their breakup. [roviLink="MN0000114342"]The Doors[/roviLink] retreated to the studio, where they sounded musically rejuvenated on the hard-rocking [roviLink="MW0000193596"]Morrison Hotel[/roviLink] (1970) and [roviLink="MW0000391383"]L.A. Woman[/roviLink] (1971). Supporting tours were marked by continued police harassment, and afterward, a depressed [roviLink="MN0000031022"]Morrison[/roviLink] left the country with his wife [roviLink="MN"]Pamela[/roviLink], eventually settling in Paris to unwind and write poetry (he had had his first collection of poems, [roviLink="BW"]The Lord and the Creatures[/roviLink], published in 1970).
- Note that an opening tag marks the beginning point for a hyperlink and a closing tag marks the end point. To create a hyperlink, first decide what type of reference it is—name, album, track, etc.—by matching the first two letters after the equal sign to an ID prefix in the table below. You can then create a link to the appropriate type of page along with a request to Rovi Cloud Services using the ID in the opening tag.
- Some tags contain only the ID prefix for the hyperlink and do not yet contain the ID. For those tags, you can either strip out the brackets entirely or you can perform a Search on the text between the tags.
- Here's a list of the hyperlink tags and what they mean:
|For This ID Prefix . . .||Link to These Requests . . .||Notes|
|MC|| Composition/Info ||Sample ID: MC0002369165.|
|MN|| Name/Info ||Sample ID: MN0000307408.|
|MQ|| Performance/Info ||Sample ID: MQ0001169372.|
|MR|| Release/Info ||Sample ID: MR0003091845.|
|MT|| Song/Info ||Sample ID: MT0043260653.|
|MW|| Album/Info ||Sample ID: MW0001892129.|
|other|| Not applicable ||Strip out tags with any other prefix.|
Special Characters in Response Data
- Rovi data is UTF-8 encoded, with some characters specified as HTML character entity references. The HTML entity references include both named character references (such as <, &, and ) and decimal number character references (such as ś and —).
- HTML entity references are recognized as valid HTML characters by all modern Web browsers.
HTTP Response Error Codes
- The status of a data request is reported in the first two elements of the message body, the status and code elements. This is the HTTP status code, which reports the success the server had in understanding the request and obtaining the requested data. Successfully processed requests return status of OK and a code 200.
- The API returns the following HTTP response error codes:
||Generally caused by an incorrectly formatted request.
||The specified API key [apikey] is not valid.
||The specified date range of [range_duration_specified_days] days is longer than the maximum allowed of 7 days.
||The specified end_date [end_date] is not valid.
||The specified errorcode_limit [errorcode_limit] is not valid.
||The specified format [format] is not valid.
||The specified limit [limit] is not valid.
||The specified method_limit [method_limit] is not valid.
||The specified service_dev_key [service_dev_key] is not valid.
||The specified service_key [service_key] is not valid.
||The specified sig [sig] is not valid.
||The specified site_id [site_id] is not valid.
||The specified start_date [start_date] is not valid.
||Account Over Queries Per Second Limit
||More requests per second than is allowed for the API key.
||Account Over Rate Limit
||Number of requests exceeds the limit allowed by your subscription level.
||The API key you are using to access the API has not been approved or has been disabled.
||You have not been granted permission to access the requested method or object.
||The API key in your request was not recognized or the signature was incorrect.
||Rate Limit Exceeded
||The service you requested is over-capacity.
||The referring URL is not recognized. This may occur if the API key is tied to a referring URL.
||The server did not find anything that matched the request. Typically this means that no resource (such as a movie, album, or image) matched the specifications in the request.
||Request URI Too Long
||The request is too long.
||Internal Server Error
||The server is experiencing a technical problem.
||A gateway processing the request received an invalid response from the API server or another server.
||API Maintenance/Service Unavailable
||The API server is temporarily unavailable.
||A gateway processing the request did not receive a response from the API server or another server before it timed out.
- Your second resource, after the documentation in these pages, is the Rovi Cloud Services Forum. The Forum is the place to go for:
- Known issues
- Release notes
- General discussion
- Questions and answers
- Suggestions and feature requests
- For announcements, don't forget to check our Developer Blog. Keep up to date with Rovi Cloud Services news and upcoming events.
|Rovi Cloud Services has a Twitter handle: @RoviAPI. Follow us to receive product updates, operational notices, and other interesting tidbits about APIs, fluffy clouds, and the rapidly evolving world of digital entertainment!|