Designing Your Video Data Application

You have a vision for your app. Here's what you need to know to make your vision a reality.

Your Home Page

The entry to your Rovi Video app can begin in several ways:

1. A presentation of featured content from your catalog of movies and TV series. You can get Rovi IDs for your catalog with Rovi Catalog Matching.
2. A text search for a movie, TV program, or person working in movies or TV:
   • Search
   • SingleStageSearch
   • Video/Info (returns only the top search result)
   • Name/Info (returns only the top search result)
3. A search on a field-level characteristic that applies to movies or television:
   • FilterBrowse

Roadmap to Rovi Video IDs

In the data returned by most API responses will be IDs of people, movies, and TV programs that you can use as links to additional API requests.

To feature people named in Rovi Video responses, grab IDs from the following requests and provide links to Name API requests:

• Video/Awards
• Video/Cast
• Video/Crew
• Video/Related
• For a complete list of requests that return name IDs, click here.

To feature movies and TV shows, grab Cosmo IDs from the following responses and provide links to Video API requests:

• Name/Credits
• Name/Schedule
• Video/Related
• Video/Season/Info
• Video/Season/Episodes
• Results from search requests.

Here's a roadmap to building pages from the Rovi IDs returned in responses:

The Top-Level Requests: The Info Requests

Rovi Video provides three top-level requests:

• Video/Info
• Name/Info
• Video/Season/Episode/Info

As shown below in the sample Info response, these Info requests return not only core information, they also return preformatted requests for subsidiary information. And they can also return that subsidiary information. Rovi Video gives you the flexibility to get a group of related information with a single Info request or to get just subsidiary information with subsidiary requests.

If you also use Rovi Search or Rovi Recommendations, you'll notice that those requests also return Info responses.

Here are some design considerations when using the Info requests:

• An Info response tells you what subsidiary data is available: if a review or biography is not available, for example, the response will not include the preformatted request for the review or biography. This feature allows your application the following program control options when parsing an Info response:
  • Grab an available request and offer the data as a link.
  • Grab an available request, execute it, and present the data.
  • If a request is unavailable, execute an alternative request.
• You don't have to make separate requests for subsidiary information. An Info response can include subsidiary information in the response. You can, for example, include a review in an Info response by specifying that as part of the Info request. Use this feature in the following cases:
  • To build a page around data and subsidiary data you already know is available.
  • To present whatever data is available using appropriate program controls. Note: some subsidiary requests return huge amounts of data. For these requests, it's better to make a separate call so you can specify parameters that paginate the response data.

A Sample Info Response

Here's a response to a Name/Info request for Conan O'Brien. Note the data returned for the subsidiary requests web and themes.

http://api.rovicorp.com/data/v1.1/name/info?apikey=apikey&sig=sig&cosmoid=100728&format=json&
include=web,themes.

Page Control: Offset and Count

Some requests return enormous amounts of information. Name/Filmography, a subsidiary request, returns over 175 items for Steven Spielberg.

To control the amount of data you receive in a response, subsidiary requests that return lists of data offer the parameters offset and count to set the starting point and number of items to return. Use these parameters in combination with page forward and page reverse controls.

So How Do I Start?

Let's start with that vision of yours. Here are some ideas for creating compelling content on any page, including a home page:

Present a Search Box

• To return search results as the user types, call SingleStageSearch.
• To have the user enter the full search query, call one of the following:
  • Search
  • Video/Info (for the top search result only)
  • Name/Info (for the top search result only)
  • Consider also calling Autocomplete to predict search names or titles as the user types.
• Consider allowing the user to select the entitytype they are searching for—credit, movie, TV series, or one-time-only (program).
• Present a page based on the user's selection.
• Use the IDs in responses to build out your pages, adding links to other pages as shown above in Roadmap to Rovi Video IDs.

Feature a TV Series

For a TV series, show all of the episodes of every season.

1. Grab the Cosmo ID of the series from a response that returns Cosmo IDs:

2. Call Video/Info with the include parameter values that return the data you want to present:

3. From the response, grab and use the data you want.
4. To present complete season information, provide links to the following requests with include=all parameters:

5. Use the IDs in responses to build your pages out, adding links to other pages as shown above in Roadmap to Rovi Video IDs.

Feature a Movie

1. Grab the Cosmo ID of the movie from a response that returns Cosmo IDs:

2. Call Video/Info with the include parameter values that return the data you want to present:

3. From the response, grab and use the data you want.
4. Call Similar to add recommendations of similar shows.
5. Use the IDs in responses to build your pages out, adding links to other pages as shown above in Roadmap to Rovi Video IDs.

Feature a Person in Movies or Television

1. Grab the ID of the person from a response that returns name IDs. For a complete list of requests that return name IDs, click here.
2. Call Name/Info with the include parameter values that return the data you want to present. Note: these values may return large amounts of data. To control the amount of data returned, make separate requests instead using the offset and count parameters.

3. From the response, grab and use the data you want.
4. Use the IDs in responses to build your pages out, adding links to other pages as shown above in Roadmap to Rovi Video IDs.