Build Pages Around Movies and TV Shows

Rovi TV Listings offers extensive and continuously updated data and images for a movie or TV show, including a schedule of upcoming TV broadcasts. The broadcast schedule for a particular movie or show is available for any time period within the next two weeks (or previous two weeks).

The data available for movies and programs includes:

• Images
• Description
• Parental ratings
• Seasons of a series
• Dozens of properties
• Descriptive keywords
• Nominations and awards
• Cast and crew credits and images
• Credit IDs you can use as links to celebrity pages
• A schedule of upcoming broadcasts of the movie or program

All of this data is available with just one to three calls.

You can reduce the number of calls you make by creating program pages, celebrity pages, and TV schedules that work together:

• In your TV schedule pages, show programs with links to program pages
• In your celebrity pages, show program credits with links to program pages
• In your program pages, show celebrity credits with links to celebrity pages
• With the IDs returned for these pages, you save yourself the calls you would otherwise need to get celebrity credit IDs and program IDs.

Note: Images of cast and crew members must be displayed with a photographer (author) credit if available. For images from Getty Images, the full photographer/collection/owner credit must be displayed next to the image. If space prevents that, you may omit parts of the credit to show just Getty Images or Getty, provided the full credit is displayed at the next reasonable alternative location, even if that is on another screen, if that location exists.

Before you start designing or programming a schedule of upcoming broadcasts, be sure to read the page Getting Started With Rovi REST TV Listings, and especially the section Understanding Television Services and Sources.

Designing Your Movie or Program Page

Here are design guidelines for building a page around movies and television shows.

1. 

   A Sample Movie Page
   Plan the layout around the data you want to present:
• Show images
• Parental ratings
• Show description
• Descriptive keywords
• Cast and crew images
• Cast and crew credits
• Nominations and awards
• Credit ID links to celebrity pages
• Schedule of upcoming broadcasts of the movie or program
2. Decide what properties you want to present about the show.

CC	Release year	Parental ratings
Duration	Last air date	Movie MPAA rating
Factsheet	First air date	Language of the show
Letterbox	Series ID	Language of the description
Syndicated	Series title	Full or shortened description
Streamable	Episode title	Part number in a multipart program
Color format	Season of an episode	Number of parts in a multipart program
Subtitled	Season sequence number	Program category—news, movie, sports, etc.
Subtitle language	Series sequence number	Program subcategory—crime drama, animated comedy, etc.
Descriptive keywords	Episode number in a series	Program type—movie, episode, one time only, etc.

3. Consider any properties you want for returned show images:
• JPG or PNG
• Image type
• Number of images
• Image aspect ratio
• Number of people in the image
• Horizontal and vertical resolutions
4. Decide what data you want to present for television or movie credits.
• Part name
• Credit name
• Episode title
• Type of credit
• Link to your page about the celebrity
• Whether the credit name is a celebrity
• Whether the credit name is an organization
• Image of the person (not returned for all credits)
5. Decide what data you want to present for awards and award nominations.
• Year
• Category
• Show title
• Show medium
• Type of award
• Award or nomination
• Whether each recipient is a celebrity
• Whether each recipient is an organization
• Whether to link to a celebrity page based on the data available about each recipient:
  • Images
  • Awards
  • Review
  • Credits
  • Summary
  • TV season data
  • TV episodes data
6. Decide what data you want to present about seasons in a series.
• Season year
• Season name
• Season number
• Season end year
• Parental ratings
• Season type—none, season, or special
• Number of episodes in the season
7. For an upcoming broadcast schedule, decide whether to offer local or, in the US, national listings.
• Local listings require a call to get the service ID of the television service the user is watching.
• The service ID for US national listings do not require an additional call, but the response does not return channel numbers. Viewers generally know what local channels these national sources appear on.
8. Decide what data you want to display for a broadcast schedule.
• Data about the local television service (for more detail, see the response object Service)
  • City served
  • Name of the service
  • Name of the service provider
  • Type of service: cable, satellite, broadcast, etc.
• Decide what channel data you want to present and how you want to present it.
  • Channel number (for local listings)
  • Full name of the source of channel programming
  • Call letters for the source of channel programming
  • Display name for the source of channel programming
  • Logo for the source of channel programming (requires an additional call for each logo)
• Decide what program data you want to present and how you want to present it. You can, for example, present information in icons, font colors, or background colors and show a legend for what each means.
  • HD
  • CC
  • DSS
  • DVS
  • SAP
  • Color
  • Dolby
  • Sports
  • Stereo
  • Subtitles
  • Letterbox
  • Episode title
  • Sign language
  • TV parental rating
  • Program description
  • Program or series title
  • Type: new, live, taped, repeat
  • Category: news, movie, music, sports, lifestyle, children's
  • Subcategory
9. Consider listing similar movies or shows on the page to help your customers discover other movies or programs they might like. See the Similar request available from Rovi Recommendations.

Building Your Movie or Program Page

With your design in mind, build your page as follows.

1. 

   A Sample TV Show Page
   Get the program ID for the show from one of these sources:
• In your TV schedules, add links to programs.
• In your celebrity pages, add links to programs in lists of credits, awards, and nominations.
• Provide a search box as input to a Search request. Consider using Autocomplete or SingleStageSearch to predict the search.
• Offer a list of similar shows on your movie and program pages by calling or linking to Similar.
2. If you want to provide a schedule of upcoming broadcasts of the show, get the service ID for the television service from one of these sources:
• For a local television service, call listings/services with the country and, for the US and Canada, a postal code. From the response, offer the list of service names to choose from.
• For US national services, you can use any of the following service IDs:

Time Zone	Complete (87+ Listings)	Widget (30+ Listings)
Eastern	80001	84801
Central	80002	84800
Pacific	80004	84798

3. Call listings/programdetails with the program ID from step 1 and, optionally, the service ID from step 2.
• For the include parameter, select the data you decided to return.
  • Image
  • Award
  • Credit
  • Keyword
  • Program
  • Seasons
• To return an upcoming broadcast schedule, specify the serviceid, startdate, duration, and inprogress parameters.
  • The startdate parameter defaults to now, and duration defaults to two weeks.
  • The inprogress parameter defaults to false, so specify true if you want to return broadcasts that are currently airing.
• To get the best images for your movie and program pages, see the section "Getting Images for Movie and Program Pages" in Getting Started With Rovi REST TV Listings.
• Request a compressed response to reduce data transfer time: include Accept-Encoding: gzip,deflate in the HTTP header.
• Grab the data in the response that you decided in your design steps to display.
• Paint the data.
4. Call Similar if you want to list similar movies or programs.