Jump to: navigation, search

Introduction to the REST TV Listings API

Rovi REST TV Listings gives you access to the television database created by TV Guide, the popular weekly American television magazine. Today that database takes in 5 million program changes every 24 hours and powers TV data, images, and schedules in magazines, websites, and television program guides in over three dozen countries.

Rovi TV Listings is designed by media professionals and software architects for television fans who also happen to be application developers. This 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.

Overview of the API

The Rovi REST TV Listings API returns the following data:

• Television service providers in an area.
• The channel lineup and channel logos for a television service.
• TV listings and channel logos for a television service.
• TV listings and program images for a television service. Note: program images to be added shortly.
• Program data, images, and a schedule of upcoming broadcasts.
• Celebrity data, images, and a schedule of upcoming broadcast appearances.

API Requests

To receive data from the REST TV Listings API, 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.

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.
• One to three optional path segments that specify parameter values.
• 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 of the arguments in the query component authenticate your access to the API server:
  • An API key. Request your free API key here.
  • A signature. The signature is a calculated value based on the current time, your API key, and a secret key you receive with your API key.

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/optional parameters/ functionRequest?parameter=value [&parameter=value]...[&parameter=value]

where:

Element	Means...
service	The service requested.
version	The version of the service, consisting of the letter v plus the version number.
function	The function.
optional paramaters	Optional parameters.
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 listings/programdetails request for information about the TV series The Simpsons—including the seasons—and a broadcast schedule for the show on Time-Warner Cable in Beverly Hills, California:

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. If you're testing the call in a browser, use our online signature generator to perform the calculation.

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 requests 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 contain the response status 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.
   • Present the data on your device, website, or application.
   • Use database IDs in the data to present 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 to Images and Trailers

To decrease response time, requests for images and trailers return URLs to image and audio files. Design your application to either automatically execute those URLs or provide links or icons so users can execute them.

Note: Access to certain images and trailers is governed by your subscription level.

HTML Characters and Tags in Text Responses

Text data returned by the following requests may contain HTML characters and tags:

• The listings/programdetails program description elements <Copy> and <CopyText>.
• The listings/celebritydetails Factsheet response element <Details>.

Program Descriptions

Movie and program descriptions returned by listings/programdetails may be HTML-formatted or plain text. The default is plain text. HTML-formatted descriptions may contain special HTML characters and tags that are ready to be dropped into a web page. Here's an example:

Four lifelong girlfriends take action when one (Ellen Burstyn) has a falling-out with her daughter (Sandra Bullock). A solid veteran cast can't save this muddled adaptation of author Rebecca Wells' works. Directorial debut for Oscar-winning screenwriter Callie Khouri (&#147;Thelma &#38; Louise&#148;). Bette Midler co-executive produced.<BR>

Here's what the description looks like in a web page:

Four lifelong girlfriends take action when one (Ellen Burstyn) has a falling-out with her daughter (Sandra Bullock). A solid veteran cast can't save this muddled adaptation of author Rebecca Wells' works. Directorial debut for Oscar-winning screenwriter Callie Khouri (“Thelma & Louise”). Bette Midler co-executive produced.

Factsheet Details

The listings/celebritydetails request returns HTML-formatted biographical factsheets. Here's an example:

<UL><LI>Moved to L.A. after college and did some writing for <I>Good Times</I> during the 1970s.&nbsp; <LI>Helped raise $430,000 for victims of Hurricanes Katrina and Rita by auctioning off a one-of-a-kind Porsche Carrera GT. <LI>Collects motorcycles and antique cars, and writes a column for Popular Mechanics called Jay Leno's Garage. <LI>Wrote several books, including <I>How to Be the Funniest Kid in the Whole Wide World (or Just in Your Class)</I>, a collection of jokes and riddles that also gives advice to kids on succeeding as a comedian. </LI></UL>

Here's what the factsheet looks like in a web page:

• Moved to L.A. after college and did some writing for Good Times during the 1970s. 
• Helped raise $430,000 for victims of Hurricanes Katrina and Rita by auctioning off a one-of-a-kind Porsche Carrera GT.
• Collects motorcycles and antique cars, and writes a column for Popular Mechanics called Jay Leno's Garage.
• Wrote several books, including How to Be the Funniest Kid in the Whole Wide World (or Just in Your Class), a collection of jokes and riddles that also gives advice to kids on succeeding as a comedian.

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:

See Also

• REST TV Listings Home
• Data Objects
• API License and Usage
• Rules and Enumerations
• Frequently Asked Questions
• Getting Started With Rovi REST TV Listings