Returns information about an episode in a television series. This request provides an alternative way to make Video/Info requests for episodes in a series, and offers the same parameters and response as Video/Info.
Like Video/Info, this request provides optional arguments to include responses from other Video API requests. This may return a large amount of data. To speed data transmission, do the following:
Optional parameters give you control over several features:
Program information | Upcoming broadcast schedule | Response format |
---|---|---|
|
|
|
video/season/season/ episode/episode/info? |
video=video cosmoid=cosmoid iguideid=iguideid |
&apikey=apikey&sig=sig [&include=include] [&format=format] [&country=country] [&language=language] [&titletype=titletype] [&serviceid=serviceid] [&starttime=starttime] [&duration=duration] [&inprogress=inprogress] [&sourceid=sourceid] [&sourceinclude=sourceinclude] [&sourceexclude=sourceexclude] |
Click to re-sort
Parameter | Required | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apikey | Yes | Access code that authorizes your request for data from Rovi. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
episode | Yes | Episode number of the season. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
season | Yes | Season number of the television series. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sig | Yes | A calculated authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cosmoId | Conditional | Cosmo database ID for a television series. Cosmo is a database of television information. You can grab Cosmo IDs from responses to the following requests:
Condition: The request must contain just one of these parameters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
iguideid | Conditional | A 24-bit program ID for a television series used by the i‑Guide™ interactive digital cable TV program guide. You can get i‑Guide IDs from responses to the following requests:
Condition: The request must contain just one of these parameters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
serviceid | Conditional | Database ID of a television service for an area. Returns a schedule, or a request for a schedule, of upcoming broadcasts of the program. You can get service IDs of television services for an area with Listings/Services (a REST call) or GetServices (a SOAP call).
You can limit a returned schedule with the following optional parameters:
Condition: Required to return:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
video | Conditional | Name of a television series. This returns the top search result for that name. Replace any spaces with plus (+) or percent20 (%20) symbols. Note: This parameter currently returns only US-English results. Support for other countries and languages will be added in the future. Condition: The request must contain just one of these parameters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
country | No | Country for the language that is specified as the language parameter, stated as a two-character ISO 3166 country code. Default is US (United States). Valid country codes are:
* Includes Wales, Scotland, and Northern Ireland. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
duration | No | If you specify serviceid for a schedule of upcoming broadcasts of the program, duration determines the number of minutes the schedule will cover. You can specify 1 to 20160; the default is 20160 (14 days).
Note: The schedule is determined by starttime, duration, and inprogress. A duration shorter than 5 minutes may miss shows starting just before or after a half-hour point. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
format | No | Format of the returned data: json or xml. The default is JSON. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
include | No | Other Video Service requests to include in the request. To include awards in the response, for example, add include=awards. For multiple include values, separate the values with commas like this: include=cast,crew. You can also include the content from all of these requests with include=all. Here are the requests you can include:
For information about a request, please see the documentation for the request. Reminder: These options may return a large amount of data. To speed data transmission, do the following:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
inprogress | No | If you specify serviceid for a schedule of upcoming broadcasts of the program, inprogress determines whether shows that are in progress at starttime are included in the schedule: true or false. Default is false.
Note: The schedule is determined by duration, inprogress, and starttime. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
language | No | Language of program titles, keywords, and descriptions, stated as a two-character ISO 639 language code. Valid language codes are:
Default is en (English). If a program description is not available in the language requested, a description in another language is provided if available. The language chosen is determined by the rules shown in the Language Fallback Sequence table. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourceid | No | If you specify serviceid for a schedule of broadcasts of the episode, sourceid determines which channels will appear on the schedule. You can get source IDs from responses to a GetServiceDetails request. Note: a single television source may supply content to multiple channels.
You can specify multiple source IDs in either of the following ways:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourceexclude | No | If you specify sourceid to select the television sources to be returned, sourceexclude specifies attributes of the channels in the source ID list that you want to eliminate from the channels returned. The possible values are:
You can specify multiple sourceexclude values in either of the following ways:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sourceinclude | No | If you specify sourceid to select the television sources to be returned, sourceinclude specifies an attribute of the channels in the source ID list that you want to include in the list of channels returned. The possible values are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
starttime | No | If you specify serviceid for a schedule of broadcasts of the program, starttime determines the starting time of the schedule. The time must be specified as a DateTime value between the time of the request and two weeks in the future. The default is the time of the request.
Note: The schedule is determined by duration, inprogress, and starttime. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
titletype | No | Type of program title to return as described in the TitleType table. Most programs do not carry all title types, so we recommend using the default unless another type is required. If a program does not have the type specified, the default title is returned. |
Response | Type | Description |
---|---|---|
build | String | The software release level of the API. |
code | Integer | HTTP status code. See the status field for the text part of the code. |
duration | Integer | Server processing time in milliseconds. The difference between startTime and endTime. |
endTime | String | When the server sent the response (UTC time). |
messages | Message [ ] | Elements of a multiple HTTP response status message. |
parameters | parameters | List of the parameters included in the request. |
serverName | String | Name of the server that processed the request. |
startTime | String | When the server received the request (UTC time). |
status | String | Text part of the HTTP status code that is shown in the code field. |
Response | Type | Description |
---|---|---|
awards | VideoAward [ ] | Awards the program has been nominated for or won, returned only if the request specified an include=awards argument. |
awardsUri | String | The customized Video/Awards request, returned only if awards data is available. |
cast | VideoCast [ ] | Cast information and links to images, returned only if the request specified an include=cast argument. |
castUri | String | The customized Video/Cast request, returned only if cast data is available. |
category | ProgramCategory | Category of television program: news, movie, sports, etc. |
clip | null | Reserved for future use. |
clipUri | String | The customized Video/Clip request, returned only if video clips are available. |
color | ColorType | Color format of the program. |
crew | VideoCrew [ ] | Crew information and images, returned only if the request specified an include=crew argument. |
crewUri | String | The customized Video/Crew request, returned only if crew information is available. |
duration | Integer | Duration of a program in minutes. |
episodeTitle | String | Title of the episode in the series. |
event | VideoEvent [ ] | Information about the event shown in the program, returned only if the request specified an include=event argument. |
eventUri | String | The customized Video/Event request, returned only if event information is available. |
ids | ids | All of the IDs for the movie or program that are, or will be, recognized by the Video Service:
|
images | Image [ ] | URLs to images associated with the program, returned only if the request specified an include=images argument and your subscription level enables access to images. Images are returned in image type sequence as shown in the Image Order table. If the program is an episode, then episode images appear before images of the series master. |
imagesUri | String | The customized Video/Images request, returned only if images are available. |
keywords | keywords | Keywords for the plot structure of a program, returned only if the request specified an include=keywords argument. |
keywordsUri | String | The customized Video/Keywords request, returned only if keywords are available. |
lastAirDate | DateTime | Last date and time the program aired. |
masterTitle | String | Title of the movie, series, or program. |
moods | VideoMood [ ] | Terms that describe expressive characteristics of the movie or program, returned only if the request specified an include=moods argument. |
moodsUri | String | The customized Video/Moods request, returned only if the data is available. |
movieRating | Rating | Local film rating of a movie. |
mpaaRating | Rating | MPAA rating of a movie. |
originalAirDate | DateTime | When the program was first broadcast. |
parentalRatings | ParentalRating [ ] | Parental ratings assigned to the movie or program, returned only if the request specified an include=parentalratings argument. |
parentalRatingsUri | String | The customized Video/ParentalRatings request, returned only if the data is available. |
partNumber | Integer | Number of a program in a multipart sequence of programs. |
partTotal | Integer | Total number of parts in a multipart sequence of programs. |
programLanguage | String | Language of the program. |
programType | ProgramType | Type of program: movie, episode, etc. |
related | related | Related movies or programs, returned only if the request specified an include=related argument. |
relatedUri | String | The customized Video/Related request, returned only if the data is available. |
releaseYear | Integer | Year the program was released. |
requestedId | String | The ID in the request that applies to this response object. |
review | review | A professional review of the movie or program, returned only if the request specified an include=review argument. |
reviewUri | String | The customized Video/Review request, returned only if the data is available. |
schedule | schedule | Upcoming television broadcasts of the program, returned only if the request specified the serviceid and include=schedule arguments. |
scheduleUri | String | The customized Video/Schedule request, returned only if serviceid is specified in the request and the movie or program is appearing in an upcoming broadcast on the television service. |
seasons | VideoSeason [ ] | Links to all of the information available about seasons and episodes of a TV series, returned only if the request specified an include=seasons argument. The links include the following: |
seasonsUri | String | The customized Video/Seasons request, returned only for a series. |
secondaryTitle | String | Secondary title of the program (usually related to sports programs). |
seriesIds | seriesIds | IDs for the series that the program specified in the request belongs to:
|
starRating | Integer | Rovi editorial rating of the program. |
streamable | Integer | Whether a program is available for streaming: 1 for true or 0 for false. |
synopsis | synopsis | A synopsis of the program, returned only if the request specified an include=synopsis argument. |
synopsisUri | String | The customized Video/Synopsis request, returned only if the data is available. |
subcategory | String | Subcategory of television program: crime drama, animated comedy, etc. |
syndicated | Boolean | Whether the program is syndicated: true or false. |
themes | theme [ ] | Topics and circumstances that motivate or fit with the program, returned only if the request specified an include=themes argument. |
themesUri | String | The customized Video/Themes request, returned only if the data is available. |
tones | tone [ ] | Feelings that motivate or fit with the program, returned only if the request specified an include=tones argument. |
tonesUri | String | The customized Video/Tones request, returned only if the data is available. |
tvRating | Rating | Local television rating of the program. |