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.
- Rovi Catalog Matching is composed of three APIs:
|Catalog Matching API || The Catalog Matching API searches Rovi Cloud Services for matches to your catalog data and returns Rovi IDs for those matches, along with associated data, images, and audio samples that you can use to verify matches. Note: Access to some images and audio samples depends on your subscription level.
|Name API || The Name API delivers data about people and groups that have contributed to music, movies, and television.
|Descriptor API || The Descriptor API lists and describes the styles, genres, and categories recognized by Rovi Cloud Services and can point you to the most significant content in each genre.
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.
- 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.
- 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:
- 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.
- 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:
| service || The service requested.
| version || The version of the service, consisting of the letter v plus the version number.
|function || The function.
|functionRequest ||The function request called.
|parameter||Parameter to be passed to the function request.
|value|| Value to be assigned to the parameter.
- 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:
- 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:
- Expected responses. Normal responses should be processed as follows:
- Parse the data.
- Process the data in your application.
- 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 to Additional Requests
- Catalog Matching responses contain the same responses that Rovi Cloud Services returns for info requests:
- 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:
<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.|
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:
||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.