Overview of Rovi Catalog Matching

Rovi Catalog Matching gives you an API you can call to get Rovi IDs for your entire catalog of songs, albums, movies, and TV shows. And you can get Rovi IDs for people and groups if you organize content around celebrities.

Use Rovi Catalog Matching to add Rovi IDs to your catalog database. Then use the other Rovi Cloud Services APIs to present in-depth and up-to-date information about the items in the catalog.

The API 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 Catalog Matching is composed of three APIs:

The Catalog Matching API

The Catalog Matching API searches current, comprehensive entertainment databases for matches to your catalog data. The Catalog Matching API:

• Searches titles or names and related field-level data.
• Rates each possible match on a confidence scale of 0 to 1.
• Presents results in order of confidence level, from highest to lowest.

The Name API

The Name API accesses an exhaustive database of information about people and groups involved in music, movies, and television. For these people, the Name API:

• Provides aliases, credits, images, fact sheets, and biographies.
• Lists a filmography with links to movie or program information.
• 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 videos and trailers associated with them.

The Descriptor API

The Descriptor API reveals the styles, genres, subgenres, and categories recognized by Rovi Cloud Services. The Descriptor API:

• Provides descriptions of styles, genres, and subgenres.
• Lists the movie and program categories recognized by Rovi Video.
• Identifies the most significant content in each genre and subgenre.

Features

Rovi Cloud Services 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 the Catalog Matching API, your application sends HTTP requests to the Rovi API server, and the API server responds with the data in standard XML or JSON format.

All communications to the API server are case-sensitive URLs that consist of the following elements:

• The host URL.
• Two path segments that specify the service and the version of the service.
• Two path segments that specify the function and the function request.
• A query component that consists of arguments to be passed to the function request. The arguments are:
  • Ampersand-delimited.
  • Specified in the parameter=value format.
• Two arguments in the query component authenticate your access to Rovi Music:
  • An API key. Request your free API key here.
  • A signature. The signature is a calculated value.

Requests to the Rovi API server should be URL-encoded.

Request Syntax

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.

All requests to the API server are of the form:

http://api.rovicorp.com/service/version/function/functionRequest?parameter=value [&parameter=value]...[&parameter=value]

where:

As an example, here is the match/track request for Robert Johnson's song Cross Road Blues with values assigned to the parameters performername, include, apikey, and sig:

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

API Responses

The Rovi API server generates a response message to all messages it receives. Responses are of the form:

• JSON-formatted data that includes an HTTP response header followed by the response data. The default response is a JSON response.
• XML-formatted data that includes an HTTP response header followed by the response data.

All responses return the response status, including error codes, as HTTP status codes in the response header.

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.
   • Process the data in your application.
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 to Additional Requests

Catalog Matching responses contain the same responses that Rovi Cloud Services returns for info requests:

• name/info
• song/info
• album/info
• video/info

The info responses make available to you the full resources of Rovi Cloud Services so you can be sure that any item in your catalog matches a particular Rovi ID.

The info responses contain preformatted URLs to 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. Note, however, that the easiest way to return the data you want is to specify the response elements you want with an include parameter in the request.

In the following portion of an info response, for example, 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. 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 the user can execute them.

Note: Access to images and audio samples is governed by your subscription level and geographical location.

Special Characters 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:

HTTP Response Error Codes

The response header shows the HTTP response status code for the request. Successfully processed requests return status of OK and a code 200.

The API returns the following HTTP response error codes: