Returns information about a movie, TV series, or TV program, plus customized requests for all of the other content that is available through the Video API. These customized requests are designed to make your programming easy and efficient: in a single step you both verify availability of data and capture the requests. Before executing them, you just add the sig parameter.
The video/info request also 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 for this call give you control over several features:
Program information | Upcoming TV schedule | Images | Response format |
---|---|---|---|
|
|
|
|
video/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] [&localeresolution=localeresolution] [&sourceid=sourceid] [&sourceinclude=sourceinclude] [&sourceexclude=sourceexclude] [&formatid=formatid] [&imagecount=imagecount] [&imageoffset=imageoffset] [&imagesize=imagesize] [&imagesort=imagesort] [&imagetypeid=imagetypeid] [&zoomlevel=zoomlevel] |
Click to re-sort
Parameter | Required | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apikey | Yes | Access code that authorizes your request for data from Rovi. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sig | Yes | A calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three ASCII strings:
Express the alpha hex digits as lower case. 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 movie, program, episode, or 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 | An ID for a television program used by the i‑Guide™ interactive digital cable TV program guide. You can get i‑Guide IDs from i‑Guide and 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 | Title of a movie, television program, or television series, or keywords from the title. This searches for the most popular title with that combination of words. 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 the language parameter applies to, stated as a two-character ISO 3166 country code. Default is the default country of the language you specify (US if language is not specified). If an invalid combination of country and language is specified, US English will be returned.
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
formatid | No | If you specify Images in the include parameter, formatid specifies the size and file format of returned images. Select the format IDs you want from the Format IDs table.
Specify multiple format IDs in a comma-separated list, like this: formatid=36,44,51. Returned images meet a combination of all of the following specified filters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagecount | No | If you specify Images in the include parameter, imagecount specifies the number of images to be returned. If fewer images are available, the available images are returned without error. The default is 25.
Use imagecount and imageoffset to paginate images in the response. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imageoffset | No | If you specify Images in the include parameter, imageoffset specifies the number of images at the start of the response to skip. The default is zero.
Use imagecount and imageoffset to paginate images in the response. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagesize | No | If you specify Images in the include parameter, imagesize specifies the image sizes to be returned. Images are not dynamically resized to fit, so only available sizes are returned.
Returned images meet a combination of all of the following specified filters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagesort | No | If you specify Images in the include parameter, imagesort specifies the sort order of returned images. Images can be sorted in ascending or descending order by the following properties:
Specify a descending sort order with a minus (-) sign, like this: imagesort=-width. Note: Your access to images is governed by your subscription level. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
imagetypeid | No | If you specify Images in the include parameter, imagetypeid specifies the type of returned images. Select the IDs you want from the Image Type IDs table.
Specify multiple image type IDs in a comma-separated list, like this: imagetypeid=2,14. To change the order in which the image types are returned, use the imagesort parameter. Returned images meet a combination of all of the following specified filters:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
include | No | Other Video Service requests to include in the request. To include awards in the response, for example, add include=awards. You can specify multiple includes in either of the following ways:
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, synopses, and keywords, stated as a two-character ISO 639 language code:
Default is en (English). If content is not available in the language requested, another language is chosen as determined by the Language Fallback Sequence table. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
localeresolution | No | How the language fallback rules should be applied for any content that is not available for the specified language and country. The values are:
Default is Full. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
zoomlevel | No | If you specify Images in the include parameter, zoomlevel specifies how close up people appear in the image. Select the zoom level you want from the Image Zoom Level table.
Specify multiple zoom levels in a comma-separated list, like this: zoomlevel=2,3. To change the order in which the image zoom levels are returned, use the imagesort parameter. Returned images meet a combination of all of the following specified filters:
|
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 | The parameters that were 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, which is shown in the code field. |
Response | Type | Description |
---|---|---|
associatedAlbums | AssociatedAlbum [ ] | Albums associated with the movie or program, returned only if the request specified an include=associatedalbums argument. |
associatedAlbumsUri | string | The customized Video/AssociatedAlbums request, returned only if associated albums are available. |
associatedTracks | AssociatedTrack [ ] | Songs associated with the movie or program, returned only if the request specified an include=associatedtracks argument. |
associatedTracksUri | string | The customized Video/AssociatedTracks request, returned only if associated songs are available. |
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 | IDs for the movie or program that are recognized by Rovi DVDs or Rovi Video. |
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. |
originalTitle | string | Original title of the movie or program in fewer than 256 characters. |
originCountries | string [ ] | Countries of origin as recognized by different legal jurisdictions. Principal locations of the companies or individuals that produced the movie or program and its accompanying material, such as scripts, synopses, shot lists, inventory lists, publicity material, production records, etc. |
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. |
programLanguageCode | string | Language of the program title, synopsis, and keywords in the response, stated as a two-character ISO 639 language code. |
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. |
seasonNumber | integer | For an episode in a TV series, the season of the TV series that the episode is in. |
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: |
seasonSequence | integer | For an episode in a TV series, the episode number in the season, counting from the first episode of the season. |
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:
|
seriesSequence | integer | For an episode in a TV series, the episode number in the series, counting from the first episode of the TV series. |
starRating | integer | Rovi editorial rating of the program. |
streamable | integer | Whether a program is available for streaming: 1 for true or 0 for false. |
subcategory | string | Subcategory of television program: crime drama, animated comedy, etc. |
syndicated | Boolean | Whether the program is syndicated: true or 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. |
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. |
web | web | Internet information resources about a movie or TV program, returned only if the request specified an include=web argument. |
webUri | string | The customized Video/Web request, returned only if the data is available. |