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.

Introduction

Rovi Music is composed of three APIs:

The Music API

The Music API accesses five interlaced collections of music data:

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.

Features

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.

API Requests

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.

Request Syntax

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:

• Ampersand-delimited
• 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:

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:

• C#
• PHP
• Ruby
• Python
• Javascript
• Groovy in Soap UI

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.

API Responses

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.

Cache-Control HTTP Response Headers

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:

Types of Response

There are three types of responses you need to code for:

1. 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.
2. 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.
3. 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:

<UL> <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:

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 &lt;, &amp;, and &nbsp;) and decimal number character references (such as &#347; and &#8212;).

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:

Developer Resources

Developer Forum

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

Our forum posts are also available via RSS feed. Subscribe to the Forum RSS feed to keep up with the latest posts.

Developer Blog

For announcements, don't forget to check our Developer Blog. Keep up to date with Rovi Cloud Services news and upcoming events.

Our blog posts are also available via RSS feed. Subscribe to the Blog RSS feed to keep up with the latest posts.

Twitter Handle

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!