Build a TV Schedule in a Magazine Format

A TV schedule can be more informative and entertaining than a just a grid. It can be the starting point for exploring ideas and adventures you've never imagined before. It can itself be entertainment. If that is your vision, Rovi TV Listings offers data, images, and program images to help make that vision a reality.

Rovi TV Listings offers continuous local broadcast listings of television services in over three dozen countries. Listings are available for any time in the next two weeks (or previous two weeks).

With just one to three initial calls, you can present a schedule of up to four hours, and then one call for each period forward or backward of up to four hours.

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

Designing Your Page

Here are design guidelines for building a schedule that shows local or national television listings in a magazine format. Start by planning the layout and the data you want to include.

1. Allow for programs that start at times other than on the hour and half-hour.
2. Decide how many minutes of programming you want to show. A single response can include up to four hours, but for processing speed you should request only the data you want to display on a single screen.
3. For local listings, decide what data you want to present about the television service and how you want to present it. Here is a list of data you can present about a 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.
4. Decide what channels you want to present. You can specify channels to be returned in the request (by source ID) or you can filter out channels in the response.
• All channels
• User favorite channels
• Basic or premium subscription channels
• Special interest channels, such as sports or movies
• A channel attribute: pay-per-view, high definition, or music programming
5. Decide what channel 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. Here is a list of channel data returned in a response. For more detail, see the response objects ListingsChannel.
• HD
• PPV
• Music
• Stet (government-access channel)
• Channel number (for local listings)
• Type of service: cable, satellite, broadcast, etc.
• Logo for the source of the channel programming
• Full name for the source of the channel programming
• Call letters for the source of the channel programming
• Display name for the source of the channel programming
6. 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. Here is a list of program data returned in a response. For more detail, see the response objects LinearSchedule and ListingsAiring.
• CC
• DSS
• DVS
• SAP
• Dolby
• Stereo
• Sports
• Subtitles
• Letterbox
• Color format
• Sign language
• HD and HD format
• Program duration
• Program description
• Movie rating
• TV parental rating
• Episode title
• Program or series title
• Type: new, live, taped, repeat
• Showing type: finale, premiere, etc.
• Channel number (for local listings)
• Full name for the source of the channel programming
• Call letters for the source of the channel programming
• Display name for the source of the channel programming
• Category: news, movie, music, sports, lifestyle, children's
• Subcategory

Building Your Page

With your design in mind, do the following steps to get the data you want.

1. Get the service ID for the television service you want by calling listings/services.
• For services in the US and Canada, you need to supply a postal code. For other countries, the postal code is optional.
• 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

• Present the name of each service from the response to let the user choose the right service.
• Grab the data you decided in design step 3 to display about the service.
2. For channel data, call listings/servicedetails with the service ID from step 1.
• Do step 2 only if you need any of the following channel information (other channel information is available from step 1 or step 3):
  • Channel logos.
  • PPV, Music, or Stet.
  • Channels that are currently off air. Some channels broadcast just part of the day, and listings/servicedetails returns those channels if they broadcast any time during the next two weeks.
• Request channel source logos as follows:
  • Specify true for includechannelimages.
  • Specify the size and format of logos in one of the following ways:
    • Specify any imageformatid in the Logo category except for 2.
    • For color logos with a transparent background, specify an imagehorizontalresolution and imageverticalresolution of 92 x 36. Use a background with no white over 248 and no black under 20.
  • See also the section "Getting Channel Logos for TV Schedules" in Getting Started.
• 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 design step 5 to display.
• Grab the schedules of sources that do not broadcast 24-hours so you can label OFF AIR times. The schedules of those sources are returned in a ChannelSchedules object. Note: a single channel may broadcast two sources on different schedules.
• Paint the data you want to display. Fill in the program data with the next call.
3. Call listings/linearschedule with the service ID from step 1.
• Specify a startdate and duration that returns the time you want to display. Don't ask for four hours if you display only one or two hours.
• If you skipped step 2 and want to return only specific channels, specify the source IDs of those channels in the sourceid parameter.
• 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 design step 6 to display.
• Allow for programs that start at times other than on the hour and half-hour.
• Convert the airing times shown from UTC format to local time, applying the timezone offset returned in the Timezones object.
• Paint the data.