Add TV Program Recommendations

Rovi TV Listings offers on-going editorial recommendations for upcoming television programs in multiple countries during any time period in the next two weeks. We provide recommendations in many categories, so you can offer, say, recommendations for teens, the family, or movies for women. Although the categories vary by country, here are some common recommendations lists:

You can choose what data a recommendation list returns—schedule data, minimal program data, extensive program data, or both schedule and program data. You can sort the results by programs or schedule, and you can filter the results by specific properties, such as HD or program language. With this flexibility, you can feature recommendations in your pages in many ways, a check mark, a sidebar, a row in a schedule, a link to another page, etc.

There are two types of recommendation lists: hot lists and filtered lists. Filtered lists return only programs that broadcast within the time period you specify. Hot lists do too, but only if you request a broadcast schedule; if you request just the programs, hot lists return all of the recommendations in the list.

You can get the recommendations in a category with just two calls, one for IDs of the lists and the other for the list of recommendations. Each additional recommendation list requires an additional call.

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

Planning Your Recommendations Data

Here are step-by-step guidelines for planning your recommendations data.

1. Coordinate your recommendations with your TV schedule pages.
• Like a TV schedule, a recommendation list requires the service ID of a television service and the time period the recommendations cover. So use the service ID and time period covered by the schedule.
• Hot lists, however, will return all recommendations in the list if you request just programs (without broadcasts).
2. Decide which recommendations list or lists you want. Consider asking the user to choose the category, say, music, teens, sports, movies.
3. Decide how you want to present a recommendation. Here are a few options:
• Sidebar or boxout
• Row in a schedule
• Link to another page
• Checkmark or icon in a row
4. Decide what data you want to present with the recommendation. A recommendation can return the same data about a program as a TV schedule or a page dedicated to a show, including the following optional elements:
• Program credits
• Program images
• Broadcast schedule
• Program description
• Program credits images

Adding Recommendations

With your design in mind, do the following steps to request and display program recommendations.

1. Call GetRecommendationLists with the name of a list group that matches the locale you want.
• The default sort order returns the most popular lists first.
• In the response, grab the ID of the list you want to use.
• If you want the user to choose a category, present titles of lists they can choose from.
2. Call GetRecommendationItemsInList with the ID from the previous step.
• Use the ServiceId, StartDate, and EndDate from the page you are supplying recommendations to.
• The IncludeDataType parameter gives you the following options for the data to be returned about a recommended program:

IncludeDataType	Airing Schedule	Program Description (CopyText)	Program Images	Program Credits	Program Credits Images
Default	✓	✓	✓	✓
ProgramsOnly		✓	✓	✓	✓
AllWithProgramsSort	✓	✓	✓
ProgramsMinimal			✓
AllWithAiringsSort	✓	✓	✓
AiringsOnly	✓

• To sort the results by broadcast time and channel, choose an IncludeDataType of AllWithAiringsSort or AiringsOnly, and in the Page parameter choose SortByColumn 6 and 25. Note: Channel numbers are not returned for national listings.
• You can filter the broadcasts returned with the AiringsFilters parameter. For example, to return only broadcasts with closed-captions, filter on column 13 equals true.
• You can filter the programs returned with the ProgramsFilters parameter.
• You can filter the images returned with the Image or ImageFormatIds parameters. For example, to return JPGs within a 250 x 250 pixel box, filter on ImageFormatId 44.
• You can specify the number of program images returned with the ImageCount parameter. The default is 5.
• Grab the data in the response that you decided to display.
• Paint the data.