Getting Started With Rovi SOAP TV Listings

Rovi SOAP TV Listings is a SOAP interface that gives you programmatic access to a wealth of television metadata:

• Current broadcast schedules of television services in over three dozen countries
• Decades of accumulated data and images related to movies, programs, and celebrities
• Editorial recommendations of upcoming television programs

The major components of the API are:

In this section:

• Building an Application
• Understanding Television Services and Sources
• Calculating Local Broadcast Times
• Understanding Images
• Strategies for Getting the Images You Want
• Understanding SOAP Responses
• Understanding Error Messages
• Developer Resources

Building an Application

Ready to start? If you haven't registered yet, your first step is to register and then request an API key. These two steps give you your username, password, and API key, which are required to access the WSDLs and receive data.

WSDL Files

A WSDL file is an XML-based description of the functionality offered by a web service, written in conformance with the Web Services Description Language (WSDL) specification. Your SOAP client reads WSDL files and uses those descriptions to provide a framework you can use to quickly make requests and process responses.

Here are the WSDL files for SOAP TV Listings, which you can access by replacing the variable yourAPIkey with your API key:

• For Rovi Listings: http://api.rovicorp.com/v9/listingsservice.asmx?WSDL&apikey=yourAPIkey
• For Rovi Rich Media: http://api.rovicorp.com/v9/richmediaservice.asmx?WSDL&apikey=yourAPIkey
• For Rovi Hot List Picks: http://api.rovicorp.com/v9/recommendationservice.asmx?WSDL&apikey=yourAPIkey

Here are the components of the API in each WSDL:

Authentication

All Rovi SOAP requests are authenticated by username, password, and API key.

• Add your username and password to the SOAP header, like this:

• You append your API key to the HTTP request URI like this:
  • For Rovi Listings: http://api.rovicorp.com/v9/listingsservice.asmx?apikey=yourAPIkey
  • For Rovi Rich Media: http://api.rovicorp.com/v9/richmediaservice.asmx?apikey=yourAPIkey
  • For Rovi Hot List Picks: http://api.rovicorp.com/v9/recommendationservice.asmx?apikey=yourAPIkey

Designing and Programming Your App

1. Follow the directions provided by your SOAP client for creating a project, adding WSDL files, and creating SOAP requests.
2. Read through the sections on this page and come back to them as needed.
3. Study the Use Cases provided to help you design your application.
4. For each request you make, study the documentation of the request in the API Reference. Request only the data you need to immediately display.
5. Build and test your application.

Understanding Television Services and Sources

To design and develop a television schedule with Rovi TV data, you first need a good understanding of television services and television sources.

What is a Television Service and Service ID?

A service ID is a numeric identifier for a television service. A television service is:

A provider of a local lineup of television channels. For example:

• Dish Network, US Eastern time zone (service ID 63879)
• Local broadcast TV, Ontario, Canada (service ID 82905)
• CanalSat, France Area Channels (Central Europe) (service ID 890504)

A lineup of US national television sources, without channel numbers. These aren't real television services, rather they are collections of the most popular national broadcast and cable sources, like CNBC, HBO, and CSPAN. Programming from these sources occurs at the same time throughout a time zone and people using these listings likely know which channels these sources are on. Examples of US national sources include:

• United States national services, Pacific time zone (service ID 80004)
• United States national services, Eastern time zone (service ID 80001)

What is a Source and Source ID?

A source ID is a numeric identifier for a source of television programming, such as CNBC, HBO, and CSPAN. A source ID identifies a unique programming schedule, and some programming sources have more than one source ID. For example, there are three source IDs for Lifetime Television East, West, and high-definition.

When you request a television program schedule, you have the option to filter the response by source IDs. This gives you the option to return, for example, just HD, PPV, music, or sports channels—or to filter them out. It also gives you the option to deliver different channels to different customers if you want to track customer favorite channels.

Most channels offer programming from just one source, but some channels may broadcast more than one source on the same channel. There are two ways this happens.

One, a channel broadcasts sources at different times, on different schedules, say one source from 6:00AM to 2:00PM, and another from 2:00PM to 12:00AM.

Two, a channel broadcasts two sources, SD and HD, on the same channel number at the same time. Satellite television receivers can tune to each channel separately, so SD receivers pick up the SD source and HD the HD.

In both cases, there are two rows in your schedule for a single channel number, each with its own call letters and perhaps its own logo. For channel numbers that switch sources, this occurs when the schedule overlaps both sources.

Because of this, the unique identifier for each row is the source ID, and the globally unique identifier for a row in a television schedule is the combination of service ID and source ID.

Note also that some channels do not offer 24-hour programming. You need to decide what you want to display during times they are not broadcasting.

Calculating Local Broadcast Times

Rovi TV Listings returns program broadcast times in UTC time (Coordinated Universal Time), so you need to apply the local UTC offset to calculate the local time. We include the local offset in the information we return about a television service.

The format we use for broadcast times is YYYY-MO-DDTHH:MI:SSZ, where:

Note that the letter T precedes the time and that, to indicate UTC time, the date-time ends with the letter Z. (UTC time is also known as Zulu time.)

Here's an example: 2012-03-05T23:00:00Z. This is the broadcast time for the 6:00 pm news on March 5, 2012 in New York City. The UTC offset for that date in New York is minus 300 minutes (5 hours). Subtracting 300 minutes from the 23:00 time results in 18:00 (6:00 pm).

Because local offsets change with daylight savings time, offset information is returned with applicable start and end times like this:

Note that for the first daylight savings time change, your TV schedule would have two time periods from 1:00 am to 2:00 am local time, and that for the second change your schedule would have no 2:00 am to 3:00 am time period.

For locales that do not observe daylight savings time, the time period covers the calendar year and the offset does not change. For Regina, Saskatchewan, for example, time zone information looks like this:

Note also that time zone offsets occur on the half hour in some countries.

Understanding Images

Rovi TV Listings gives you access to over 150,000 images related to movies and television, with more added every business day. The kinds of images include:

• Cast photos
• Show imagery
• Movie posters
• TV channel logos
• TV series showcards
• Celebrity appearances

An image is typically available in over 35 different sizes and image formats.

Image Metadata

API responses do not return image files. To speed data transmission and to let you select the images you want, Rovi TV Listings returns image metadata that includes URLs to image files. You select the images you want from the metadata and include the URLs of those images in your application so the image download occurs at the final point.

Image metadata includes the following useful properties:

• Aspect ratio
• Type of image
• Image dimensions
• Legal owner of the image
• Image format (JPG or PNG)
• Number of people in the image
• Caption for some types of images
• When the image was last modified
• Orientation (portrait or landscape)
• When availability of the image expires
• Prominance of the cast members in the image
• How much of the person appears in the picture
• Image size as a percentage of the original image size
• Image credit and whether it must be displayed with the image
• An ID that all other files with the same image have in common
• Whether the image is directly relevant to the subject of the API request
• Associated celebrity name, TV channel source name, or movie or program title

Here, for example, is image metadata for a program we made up called The Cube. (Although this image is a mock up, it is similar to images returned for actual programs.) For detailed information about these properties, see the documentation for the Image object.

<Image>    <ImageUrl>http://a_fictional_show.jpg</ImageUrl>    <ImageUseType xsi:nil="true"/>    <ImageId>26051</ImageId>    <ImageTitle>The Cube</ImageTitle>    <ImageCaption>Key Art</ImageCaption>    <ObjectId>4477399</ObjectId>    <ObjectType>Program</ObjectType>    <ObjectName>The Cube</ObjectName>    <Relevancy>true</Relevancy>    <ImageCredit>NBC</ImageCredit>    <ImageCreditDisplay xsi:nil="true"/>    <ImageCastWeight>1</ImageCastWeight>    <ImageZoomLevel>3</ImageZoomLevel>    <ImageHeadcount>5</ImageHeadcount>    <ImageType>Key Art</ImageType>    <ImageFormat>jpg</ImageFormat>    <ImageHorizontalResolution>250</ImageHorizontalResolution>    <ImageVerticalResolution>142</ImageVerticalResolution>    <ImageMaintainAspectFlag xsi:nil="true"/>    <ImageExpiryDateTime xsi:nil="true"/>    <LastUpdate>2011-05-17T11:50:00.79Z</LastUpdate>    <ImageFormatId>44</ImageFormatId>    <Orientation>Landscape</Orientation>    <AspectRatio>16:9</AspectRatio>    <ImageOwner>NBC</ImageOwner>    <ParentImageId>16785528</ParentImageId>    <MaxImageScale>24.6</MaxImageScale> </Image>

Types of Images the API Returns

Here are descriptions of the image types the API returns:

The API returns images in order of image type as shown in the Image Order table. Here are the image types returned by each of the API calls that return images:

Image Filters

Some requests can return hundreds of images. To help you get the images you want, most of the calls that return images allow you to filter the images returned based on values of the following image metadata properties:

Here's an example of an image filter that returns JPGs of Dustin Hoffman in the film Outbreak that fit a bounding box of 250 x 250 pixels.

Strategies for Getting the Images You Want

The wide variety of image metadata and image filters are designed to help you get the images you want. The best strategy to get images depends on the API request and the type of application you are building.

Getting Channel Logos for TV Schedules

Channel logos are the logos of TV networks and other TV programming sources, such as CBS, HBO, and CSPAN. A TV programming source may have multiple logos. CBS, for example, has a logo with just the graphic eye and has other logos that include the letters CBS. And networks commonly have versions for local affiliates as well.

You can receive channel logos in the channel information that is returned by both GetServiceDetails and GetGridSchedule. Use the ImageFilter parameter in those calls to get the logos you want:

• To return logos by width and height, specify an ImageFormatId in the Logo category that has the dimensions you want. Most channel logos have a landscape orientation, so we recommend using an ImageFormatId (except for 2) that has a greater width than the height. The response will return the best quality logos for that that request, but if you want to select a logo by other priorities, such as widget (low resolution) or aspect ratio, choose an image count of 4 and select the logos you want from the metadata returned about each logo.
• To return small color logos with a transparent background, specify a horizontal and vertical resolution of 92 x 36. Use a background with no white over 248 and no black under 20.
• To return black or white logos with a transparent background, specify a horizontal and vertical resolution of 122 x 66 and an image count of 2. From the results, parse the links to the images and choose which one you want, the black or white.
• To return logos with a transparent background that are visible on either light or dark backgrounds, specify a horizontal and vertical resolution of 2400 x 2400 and an image count of 5. From the results, parse the links to the five images and choose which one you want:
  • White — appropriate for a dark background
  • Grayscale — appropriate for a light or dark background
  • Color Dark — color logo appropriate for dark background
  • Color Light — color logo appropriate for a light background
  • Color Dark/Light — color logo appropriate for a light or dark background.

Getting Program Images for TV Schedules

You can get images for the programs in a TV schedule with the TV schedule information you receive from GetLinearSchedule. Because of the large amount of data returned by this request, no more than one image is returned for a program. That image may be from a scene in that particular show or may be a generic image or logo for the program.

To receive program images, specify two format IDs in the ProgramImageFormatIds parameter, your first and second choice for the size and type of image you want. To return the maximum number of images, specify one format ID in the Image category and the other format ID in the Logo category.

Getting Images for Movie and Program Recommendations

You get images for movie and program recommendations with the information you receive from GetRecommendationItemsInList. The order in which images are returned depends on the program category, as shown in the Image Order table.

The best strategy for getting images of recommended programs is to specify one or two format IDs in the ImageFormatIds parameter. Then select the images you want from the metadata returned about each image.

Getting Images for Celebrity Pages

You can get images for your celebrity pages with the information you receive from GetCelebrityDetails or you can get the same images with GetMedia. GetMedia offers even more image filters to better return the images you want and eliminate the images you don't want. The order in which celebrity images are returned is shown in the Image Order table. The best strategy depends on what you want to do.

To get the best images for a particular celebrity:

• With GetCelebrityDetails, use any of the 12 image filters in the Image object, starting with ImageFormatId and ImageType and a large ImageCount. Create several combinations of filters and execute them in order of priority until you get the best images available for that page.
• With GetMedia, start with the ImageFormatIds and ImageTypes parameters. Then add any of the 12 image filters in the Image object to focus on the images you want.

To get the images that work best for a page design, across all of your celebrity pages:

• With GetCelebrityDetails, specify the ImageFormatId filter in the Image object and a large ImageCount, say 50, to get all of the images available. Then select the images you want from the metadata returned about each image.
• With GetMedia, specify one or two image formats in the ImageFormatIds parameter and specify all of the acceptable image types in the ImageTypes parameter.

Getting Images for Movie and Program Pages

You can get images for your movie and program pages with the information you receive from GetProgramDetails or you can get the same images with GetMedia. GetMedia offers even more image filters to better return the images you want and eliminate the images you don't want. The order in which images are returned depends on the program category, as shown in the Image Order table. The best strategy for getting movie and program images depends on what you want to do.

To get the best images for a particular movie or program:

• With GetProgramDetails, use any of the 12 image filters in the Image object, starting with ImageFormatId and ImageType and a large ImageCount. Create several combinations of filters and execute them in order of priority until you get the best images available for that page.
• With GetMedia, start with the ImageFormatIds and ImageTypes parameters. Then add any of the image filters in the Image object to focus on the images you want.

To get the images that work best for a page design, across all of your movie or program pages:

• With GetProgramDetails, specify the ImageFormatId filter in the Image object and a large ImageCount, say 50, to get all of the images available. Then select the images you want from the metadata returned about each image.
• With GetMedia, specify one or two image formats in the ImageFormatIds parameter and specify all of the acceptable image types in the ImageTypes parameter.

Understanding SOAP Responses

The Rovi transaction server returns all requests with a response that includes:

• A SOAP Envelope object.
• A SOAP Body object.
• The transaction response object.
• The transaction result object.
• Header elements, which report information about the transaction:
  • RequestId — A generated value that identifies the request and response.
  • ClientBatchId — Returned only if you provided a batch ID. You can use a batch ID to identify a group of requests.
  • TimeStamp — When the server started processing the request.
  • Status — The status of the transaction.
  • Errors — Errors or warnings that occurred during processing.
  • EndTimestamp — When the server finished processing the request.
  • Build — The current version of the API.
• Data elements.

Here's a sample transaction response for a GetServices request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <GetServicesResponse xmlns="http://api.rovicorp.com/v9/listings">
         <GetServicesResult>
            <RequestId xmlns="http://api.rovicorp.com/v9/common/types">e0c2520c-fc10-4b5a-af17-df907662a4ef</RequestId>
            <TimeStamp xmlns="http://api.rovicorp.com/v9/common/types">2012-11-17T00:47:08.331Z</TimeStamp>
            <Status xmlns="http://api.rovicorp.com/v9/common/types">PNE</Status>
            <Errors xmlns="http://api.rovicorp.com/v9/common/types"/>
            <EndTimestamp xmlns="http://api.rovicorp.com/v9/common/types">2012-11-17T00:47:08.331Z</EndTimestamp>
            <Build xmlns="http://api.rovicorp.com/v9/common/types">2010.06.01</Build>
            <Services>
               <Service ServiceClass="Non Cable Customer">
                  <ServiceId>80001</ServiceId>
                  <Name>Eastern - National Channels - Eastern Time Zone</Name>
                  <City>Eastern Time Zone</City>
                  <Type>National</Type>
                  <MSO>Data Services Product</MSO>
                  <MSOID>301530</MSOID>
                  <SystemName>Eastern Time Zone</SystemName>
                  <TimeZones>
                     <TimeZoneInfo>
                        <StartDateTime>2012-11-04T06:00:00Z</StartDateTime>
                        <EndDateTime>2013-03-10T07:00:00Z</EndDateTime>
                        <Offset>-300</Offset>
                     </TimeZoneInfo>
                  </TimeZones>
               </Service>
            </Services>
         </GetServicesResult>
      </GetServicesResponse>
   </soap:Body>
</soap:Envelope>

Understanding Error Messages

During application development, you are concerned about errors from three sources:

• Your development environment.

Your SOAP development environment warns you about parameter values that are missing or invalid according to the WSDL.

• The Rovi API hosting service.

The Rovi API host authorizes access and performs an initial request validation. The API host returns error messages as a single element, like this:

   <h1>403 Developer Inactive</h1>

The error messages returned by the Rovi API host are listed below in the section Error Messages From the Rovi API Hosting Service.

• The Rovi transaction server.

The Rovi transaction server returns error information in two objects in the response header:

• The Status element
• The Errors object

For details about these error messages, see the following section.

Error Messages From the Rovi API Transaction Server

The Rovi API transaction server returns error information in two objects in the response header, like this:

    <Status xmlns="http://api.rovicorp.com/v9/common/types">NPE</Status>
    <Errors xmlns="http://api.rovicorp.com/v9/common/types">
       <Error>
          <ErrorCode>502001</ErrorCode>
          <ErrorName>Listings_InvalidCopyType</ErrorName>
          <ErrorText>The CopyType is invalid.</ErrorText>
          <ErrorType>Error</ErrorType>
       </Error>
    </Errors>

The Errors object returns one or more Error objects that describe errors found. For information about errors returned for a request, see the page documenting that request.

The Status element returns the transaction status as a three-letter code, as shown in the following table.

Error Messages From the Rovi API Hosting Service

The Rovi API host returns error messages as a single element, like this:

	<h1>403 Developer Inactive</h1>

The error messages returned by the Rovi API host are listed below:

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!

↑ Top