Data/movie-api/v1.1/overview

Jump to: navigation, search

Overview of Rovi DVDs

Rovi DVDs gives you access to a world-class database of information about movies and TV series and their releases on DVDs, Blu-rays, and other formats. This is the database that powers online retailers such as AOL, iTunes, Yahoo, BestBuy, 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 DVDs has a storied heritage. It was started by musicians, filmmakers, and self-described 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 rate artists against each other or tell people what their taste should be. We wanted to rank movies under objective, relevant criteria—tones, moods, themes, genres, and subgenres—and we wanted to describe and review content 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 DVDs is designed by those same media experts, and by software architects, for movie 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 DVDs is composed of three APIs:
Movie API The Movie API delivers data, images, and trailers related to movie and TV series, including releases on DVDs, Blu-rays, and other formats.
Name API The Name API delivers data about the people that contributed to movies and television, including images and trailers, and it points you to the movies and television shows they contributed to. It also covers people in music so you can provide a seamless connection to artists’ work in music if you also use Rovi Music.
Descriptor API    The Descriptor API lists and defines the genres and subgenres used in the Movie API and points you to the top movies and TV series in each genre and subgenre.

The Movie API

The Movie API accesses a comprehensive, in-depth database about movies and TV series. Use the Movie API to:
  • Deliver a synopsis, review, and images of a movie or TV series.
  • Deliver a list of DVDs, Blu-rays, and other releases.
  • Deliver movie trailers.
  • Provide a list of related movies or TV series.
  • List cast and crew with images and links to further data.
  • For DVDs or Blu-rays, show an image, description, and list of special features.
  • Show the moods, tones, themes, keywords, attributes, genres, and subgenres that apply.
  • Use the moods, tones, themes, keywords, genres, and subgenres that apply as links to relevant movies and TV series.

The Name API

The Name API accesses an exhaustive database of information about people involved in movies and television. Use the Name API to:
  • Deliver a fact sheet or biography with images and the other names that celebrities have been known by.
  • Provide links to videos and trailers that celebrities appear in and to web resources about them.
  • List credits or a filmography with links to movie or program information.
  • List movie styles people are known for.

The Descriptor API

The Descriptor API focuses on movie genres and subgenres. The Descriptor API:
  • Provides descriptions of the movie genres and subgenres.
  • Identifies the top movies and TV series in each genre and subgenre.

Features

Rovi DVDs data features:
  • Constantly updated, always current, always relevant.
  • Subjected to rigorous copy proofing and data integrity best practices.
  • Original editorial content, including reviews, synopses, fact sheets, descriptions, and biographies.
  • Objective, relevant classification criteria based on hundreds of tones, moods, themes, attributes, 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 DVDs, 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 movie Seabiscuit, including images that are in the range of 70 to 100 pixels in both dimensions.
Elements shown in boldface are case-sensitive.
http://api.rovicorp.com/data/v1.1/movie/info?movieid=V+++284677&include=images&
imagesize=70-100x70-100&apikey=abcd1efghi23jklmnopq45rs6&sig=149522a6c3c3fee7ea629493e767ac68
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:
ElementCase SensitivePurpose
http://api.rovicorp.comNoThe host URL.
/dataYesThe service requested.
/v1.1YesThe version of the service, consisting of the letter v plus the version number.
/movieYesThe function called.
/infoNoThe function request called.
movieid=V+++284677NoParameter to pass to the function request and the value assigned to the parameter.
include=imagesNoParameter to pass to the function request and the value assigned to the parameter.
imagesize=70-100x70-100NoParameter to pass to the function request and the value assigned to the parameter.
apikey=abcd1efghi23jklmnopq45rs6NoAPI key that authorizes your use of the API.
sig=149522a6c3c3fee7ea629493e767ac68YesAuthentication 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.

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:
Response HeaderDescription
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:
  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 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 moodsUri element. When parsing this response, you know moods are inapplicable or unavailable, so you know not to offer that information. On the other hand, you know there is data available for castUri, crewUri, imagesUri, etc.
{
   {
      "cast":null,
      "castUri":"http://api.rovicorp.com/v1.1/movie/cast?format=json&apikey=4p1k3y&movieid=V+++531454",
      "crew":null,
      "crewUri":"http://api.rovicorp.com/v1.1/movie/crew?format=json&apikey=4p1k3y&movieid=V+++531454",
      "images":null,
      "imagesUri":"http://api.rovicorp.com/v1.1/movie/images?format=json&apikey=4p1k3y&movieid=V+++531454",
      "keywords":null,
      "keywordsUri":"http://api.rovicorp.com/v1.1/movie/keywords?format=json&apikey=4p1k3y&movieid=V+++531454",
      "moods":null,
      "moodsUri":null,
      "related":null,
      "relatedUri":"http://api.rovicorp.com/v1.1/movie/related?format=json&apikey=4p1k3y&movieid=V+++531454",
      "releases":null,
      "releasesUri":"http://api.rovicorp.com/v1.1/movie/releases?format=json&apikey=4p1k3y&movieid=V+++531454",
      "review":null,
      "reviewUri":"http://api.rovicorp.com/v1.1/movie/review?format=json&apikey=4p1k3y&movieid=V+++531454",
   }
}
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 links or 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 to Name/Factsheets and Name/MovieBio requests 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
Name/Factsheets responses 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>At 12, appeared in the PBS science series <I>The Voyage of the Mimi</I>, and later played Madeline Kahn's son in an ABC <I>Afterschool Special</I> titled \"Wanted: The Perfect Guy.\" <LI>Has appeared in several Kevin Smith films, including <I>Mallrats</I>, <I>Chasing Amy</I>,<I> Jay and Silent Bob Strike Back</I> and <I>Jersey Girl</I>. <LI>Vigorously campaigned for Al Gore and John Kerry and appeared at the 2004 Democratic National Convention. <LI>Testified before Congress in support of funding medical research for Ataxia-Telangiectasia after befriending a young boy who suffers from the degenerative disease. <LI>An avid card player who has appeared on <I>Celebrity Poker Showdown</I>. <LI>Hosted <I>Saturday Night Live</I> four times between 2000 and 2008.</LI></UL>

Dropped into a web page, the above text looks like this:

  • At 12, appeared in the PBS science series The Voyage of the Mimi, and later played Madeline Kahn's son in an ABC Afterschool Special titled "Wanted: The Perfect Guy."
  • Has appeared in several Kevin Smith films, including MallratsChasing Amy, Jay and Silent Bob Strike Back and Jersey Girl.
  • Vigorously campaigned for Al Gore and John Kerry and appeared at the 2004 Democratic National Convention.
  • Testified before Congress in support of funding medical research for Ataxia-Telangiectasia after befriending a young boy who suffers from the degenerative disease.
  • An avid card player who has appeared on Celebrity Poker Showdown.
  • Hosted Saturday Night Live four times between 2000 and 2008.

Rovi Hyperlink Tags in Text Responses
Movie/Synopsis, Movie/Description, and Name/MovieBio 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 biography with several tags:

Dark-haired [rovilink=\"D\"]comedic[/rovilink] actor [rovilink=\"P 16032\"]Jon Cryer[/rovilink] remains best-known for his lovable performance as Duckie Dale in the 1986 [rovilink=\"D\"]teen movie[/rovilink] [rovilink=\"V 39095\"]Pretty in Pink[/rovilink]. Even though he was 21 years old playing a high school senior, he exhibited a vulnerable yet goofy freshness unlike most other teen stars. The son of Broadway performers, he was schooled in the Bronx before making his film debut in the [rovilink=\"D\"]romantic comedy[/rovilink] [rovilink=\"V 35542\"]No Small Affair[/rovilink] as a young photographer obsessed with [rovilink=\"P103370\"]Demi Moore[/rovilink]. He made some unfortunate movies after [rovilink=\"V 39095\"]Pretty in Pink[/rovilink], including the [rovilink=\"V 17076\"]Ferris Bueller[/rovilink] knock-off [rovilink=\"V 33343\"]Morgan Stewart's Coming Home[/rovilink], which suggested unfair comparisons with actor [rovilink=\"P 8627\"]Matthew Broderick[/rovilink]. Other forgettable movies followed until he was cast as the star of the [rovilink=\"D\"]sitcom[/rovilink] [rovilink=\"V\"]The Famous Teddy Z[/rovilink], which was then followed by several other short-lived [rovilink=\"D\"]sitcoms[/rovilink]. After appearing in the anarchic [rovilink=\"D\"]comedy[/rovilink] [rovilink=\"V 23268\"]Hot Shots![/rovilink], he proved fairly successful with offbeat [rovilink=\"D\"]comedies[/rovilink] and independent films. He helped write the talky [rovilink=\"D\"]romantic comedy[/rovilink] [rovilink=\"V 134913\"]The Pompatus of Love[/rovilink] then starred in the similarly themed [rovilink=\"V 181499\"]Plan B[/rovilink]. He teamed up with director [rovilink=\"P238819\"]Richard Schenkman[/rovilink] to write the offbeat [rovilink=\"D\"]comedy[/rovilink] [rovilink=\"V 162530\"]Went to Coney Island on a Mission From God...Be Back by Five[/rovilink]. \r\n\r\nIn 2003, Cryer re-teamed with Hotshots! co-star Charlie Sheen for the sitcom Two and a Half Men, which proved to be a massive success. The show was so popular that it stayed on the air, even after Sheen left in 2011, with Ashton Kutcher filling in the empty spot in the cast.

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, movie, etc.—by matching the first one or two letters in the ID 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 hyperlink tags appearing in movie biographies and what they mean:
For This ID Prefix . . .Link to These Requests . . .Notes
MN Name/Info Sample ID: MN0001377538.
P Name/Info Sample ID: P 16032.
V Movie/Info Sample ID: V 39095.
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 &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 Status 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:
CodeError MessageDescription
400 Bad Request Generally caused by an incorrectly formatted request.
400 ERR_INVALID_APIKEY The specified API key [apikey] is not valid.
400 ERR_INVALID_DATE_RANGE_EXCEEDS_7_DAY_MAX The specified date range of [range_duration_specified_days] days is longer than the maximum allowed of 7 days.
400 ERR_INVALID_END_DATE The specified end_date [end_date] is not valid.
400 ERR_INVALID_ERRORCODE_LIMIT The specified errorcode_limit [errorcode_limit] is not valid.
400 ERR_INVALID_FORMAT The specified format [format] is not valid.
400 ERR_INVALID_LIMIT The specified limit [limit] is not valid.
400 ERR_INVALID_METHOD_LIMIT The specified method_limit [method_limit] is not valid.
400 ERR_INVALID_SERVICE_DEV_KEY The specified service_dev_key [service_dev_key] is not valid.
400 ERR_INVALID_SERVICE_KEY The specified service_key [service_key] is not valid.
400 ERR_INVALID_SIG The specified sig [sig] is not valid.
400 ERR_INVALID_SITE_ID The specified site_id [site_id] is not valid.
400 ERR_INVALID_START_DATE The specified start_date [start_date] is not valid.
403 Account Over Queries Per Second Limit More requests per second than is allowed for the API key.
403 Account Over Rate Limit Number of requests exceeds the limit allowed by your subscription level.
403 Developer Inactive The API key you are using to access the API has not been approved or has been disabled.
403 Forbidden You have not been granted permission to access the requested method or object.
403 Not Authorized The API key in your request was not recognized or the signature was incorrect.
403 Rate Limit Exceeded The service you requested is over-capacity.
403 Unknown Referrer The referring URL is not recognized. This may occur if the API key is tied to a referring URL.
404 Not Found 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.
414 Request URI Too Long The request is too long.
500 Internal Server Error The server is experiencing a technical problem.
502 Bad Gateway A gateway processing the request received an invalid response from the API server or another server.
503 API Maintenance/Service Unavailable The API server is temporarily unavailable.
504 Gateway Timeout A gateway processing the request did not receive a response from the API server or another server before it timed out.

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!
 
Personal tools