V1.MetaData.VideoService.Video:Info

Jump to: navigation, search

Video/Info

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 Service. 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:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

Optional parameters for this call give you control over several features:

Program informationUpcoming broadcast schedule   Response format
  • include
  • country
  • language
  • titletype
  • duration
  • starttime
  • serviceid
  • inprogress
  • sourceid
  • sourceexclude
  • sourceinclude
  • format

Syntax

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] [&sourceid=sourceid] [&sourceinclude=sourceinclude] [&sourceexclude=sourceexclude]] [&formatid=formatid] [&imagecount=imagecount] [&imageoffset=imageoffset]

Request Example 1

Request information about The Simpsons television series.
http://api.rovicorp.com/data/v1/video/info?apikey=apikey&sig=sig&cosmoid=7903

Request Example 2

Request information about the movie Terminator 2: Judgment Day with a title less than 15 characters and links to images.
http://api.rovicorp.com/data/v1/video/info?apikey=apikey&sig=sig&cosmoid=55394&include=images
&titletype=1

Request Example 3

Request information in XML format about the series Two and a Half Men and return a request link for a schedule of broadcasts over the next two weeks on Time Warner Cable in Beverly Hills, California.
http://api.rovicorp.com/data/v1/video/info?apikey=apikey&sig=sig&cosmoid=3899277&serviceid=360861
&format=xml

Request Example 4

Request information about the movie Terminator 2: Judgment Day and a schedule of HD broadcasts of the movie on any of the movie channels on Time Warner Cable in Southern Manhattan over the next week, including broadcasts that are currently on.
http://api.rovicorp.com/data/v1/video/info?apikey=apikey&sig=sig&cosmoid=55394&include=schedule
&serviceid=60795&duration=10080&inprogress=true&sourceinclude=HD&sourceid=433,1263,1535,
2196,2419,3818,16137,15591,17116,19433,20419,21586,22700,23458,27330

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikey Yes Access code that authorizes your request for data from Rovi.
sig Yes A calculated authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

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 or a television series, season, or program. 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:

  • video
  • cosmoid
  • iguideid
iguideid Conditional A 24-bit program 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:

  • video
  • cosmoid
  • iguideid
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:

  • duration
  • starttime
  • inprogress

Condition: Required to return:

  • The URL to the schedule in the scheduleUri element.
  • The schedule requested with the include=schedule argument.
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:

  • video
  • cosmoid
  • iguideid
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:
  • AR
Argentina
  • SV
 El Salvador
  • NI
Nicaragua
  • AT
Austria
  • FI
 Finland
  • NO
Norway
  • BE
Belgium
  • FR
France
  • PA
Panama
  • BM
Bermuda
  • DE
Germany
  • PE
Peru
  • BO
Bolivia
  • GT
Guatemala
  • PL
Poland
  • BR
Brazil    
  • PT
Portugal
  • CA
Canada
  • HN
Honduras
  • ES
Spain
  • CL
Chile
  • IE
Ireland
  • SE
Sweden
  • CO
Colombia
  • IT
Italy
  • CH
Switzerland
  • CR
Costa Rica
  • JM
Jamaica
  • TR
Turkey
  • DK
Denmark
  • LU
Luxembourg   
  • GB
United Kingdom*
  • DO
Dominican Republic   
  • MX
Mexico
  • US
United States
  • EC
Ecuador
  • NL
Netherlands
  • VE
Venezuela

* 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 All or Images in the include parameter, formatid specifies the size and file format of returned images. The format IDs available are shown in the Format IDs table. To select multiple format IDs, specify the IDs as a comma-separated list like this formatid=36,44,51.

Note: Your access to images is governed by your subscription level.

imagecount No If you specify All or Images in the include parameter, imagecount specifies the number of images to be returned.
imageoffset No If you specify All or Images in the include parameter, imageoffset specifies the number of first images to be returned. Counting from zero as the first item in the list of images, the number of the first images you want. The default is zero. Use imagecount and imageoffset to paginate returned results.
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:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
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:
  • da
Danish
  • fr
French
  • pl
Polish
  • nl
Dutch
  • de
German
  • pt
Portuguese
  • en
English    
  • it
Italian
  • es
Spanish
  • fi
Finnish
  • no
Norwegian    
  • sv
Swedish
  • fl
Flemish
  • tr
Turkish

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:

  • In multiple arguments, like this: sourceid=14019&sourceid=11284&sourceid=10395.
  • In a single argument as a comma-separated list, like this: sourceid=14019,11284,10395.
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:
  • HD
  • PPV
  • Music

You can specify multiple sourceexclude values in either of the following ways:

  • In multiple arguments, like this: sourceexclude=HD&sourceexclude=PPV.
  • In a single argument as a comma-separated list, like this: sourceexclude=HD,PPV.
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:
  • HD
  • PPV
  • Music
Only channels in the source ID list that meet that attribute will be returned.
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

Response Header

ResponseTypeDescription
buildStringThe software release level of the API.
codeIntegerHTTP status code. See the status field for the text part of the code.
durationIntegerServer processing time in milliseconds. The difference between startTime and endTime.
endTimeStringWhen the server sent the response (UTC time).
messagesMessage [ ]Elements of a multiple HTTP response status message.
parametersparametersList of the parameters included in the request.
serverNameStringName of the server that processed the request.
startTimeStringWhen the server received the request (UTC time).
statusStringText part of the HTTP status code that is shown in the code field.

Response for Video/Info

ResponseTypeDescription
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:
  • iguideId
  • cosmoId
  • amgMovieId
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:
  • seriesId
  • iguideSeriesId
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.

JSON Response Example

Here's the response to Request Example 1. It is formatted with extra spaces and carriage returns to make it easy to read.
{
   "status":"ok",
   "code":200,
   "messages":null,
   "build":"1.7.3.0",
   "parameters":{
      "apiKey":"4p1k3y",
      "id":"7903"
   },
   "serverName":"tul1cssw1",
   "startTime":"2011-10-17T23:04:35.6253289Z",
   "endTime":"2011-10-17T23:04:35.9534476Z",
   "duration":328,
   "video":{
      "ids":{
         "amgMovieId":null,
         "cosmoId":"7903",
         "iguideId":7903
      },
      "seriesIds":null,
      "masterTitle":"The Simpsons",
      "secondaryTitle":"",
      "episodeTitle":null,
      "category":"Other",
      "color":"Color",
      "lastAirDate":null,
      "originalAirDate":"1989-12-17T00:00:00Z",
      "programType":"Series",
      "releaseYear":1989,
      "duration":30,
      "subcategory":"animated comedy",
      "syndicated":true,
      "programLanguage":"English",
      "partNumber":null,
      "partTotal":null,
      "streamable":1,
      "movieRating":null,
      "parentalRatings":null,
      "parentalRatingsUri":"http:\/\/api.rovicorp.com\/v1\/video\/parentalratings?format=json&apikey=4p1k3y&cosmoid=7903",
      "starRating":null,
      "tvRating":"None",
      "mpaaRating":null,
      "cast":null,
      "castUri":"http:\/\/api.rovicorp.com\/v1\/video\/cast?format=json&apikey=4p1k3y&cosmoid=7903",
      "crew":null,
      "crewUri":"http:\/\/api.rovicorp.com\/v1\/video\/crew?format=json&apikey=4p1k3y&cosmoid=7903",
      "awards":null,
      "awardsUri":"http:\/\/api.rovicorp.com\/v1\/video\/awards?format=json&apikey=4p1k3y&cosmoid=7903",
      "images":null,
      "imagesUri":"http:\/\/api.rovicorp.com\/v1\/video\/images?format=json&apikey=4p1k3y&cosmoid=7903",
      "clip":null,
      "clipUri":"http:\/\/api.rovicorp.com\/v1\/video\/clip?format=json&apikey=4p1k3y&cosmoid=7903",
      "seasons":null,
      "seasonsUri":"http:\/\/api.rovicorp.com\/v1\/video\/seasons?format=json&apikey=4p1k3y&cosmoid=7903",
      "schedule":null,
      "scheduleUri":null,
      "event":null,
      "eventUri":null,
      "keywords":null,
      "keywordsUri":"http:\/\/api.rovicorp.com\/v1\/video\/keywords?format=json&apikey=4p1k3y&cosmoid=7903",
      "moods":null,
      "moodsUri":"http:\/\/api.rovicorp.com\/v1\/video\/moods?format=json&apikey=4p1k3y&cosmoid=7903",
      "related":null,
      "relatedUri":"http:\/\/api.rovicorp.com\/v1\/video\/related?format=json&apikey=4p1k3y&cosmoid=7903",
      "review":null,
      "reviewUri":null,
      "synopsis":null,
      "synopsisUri":"http:\/\/api.rovicorp.com\/v1\/video\/synopsis?format=json&apikey=4p1k3y&cosmoid=7903",
      "themes":null,
      "themesUri":"http:\/\/api.rovicorp.com\/v1\/video\/themes?format=json&apikey=4p1k3y&cosmoid=7903",
      "tones":null,
      "tonesUri":"http:\/\/api.rovicorp.com\/v1\/video\/tones?format=json&apikey=4p1k3y&cosmoid=7903",
      "requestedId":"7903"
   }
}

XML Response Example

Here's the response to Request Example 3. Note the request link in the scheduleUri element.
<VideoDetail xmlns="com.rovicorp.metadataservice" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <status>ok</status>
  <code>200</code>
  <messages i:nil="true"/>
  <build>1.7.3.0</build>
  <parameters>
    <apiKey>4p1k3y</apiKey>
    <id>3899277</id>
    <format>xml</format>
    <serviceid>360861</serviceid>
  </parameters>
  <serverName>tul1cssw1</serverName>
  <startTime>2011-10-17T23:09:28.1040882Z</startTime>
  <endTime>2011-10-17T23:09:28.8071997Z</endTime>
  <duration>703</duration>
  <video>
    <ids>
      <amgMovieId i:nil="true"/>
      <cosmoId>3899277</cosmoId>
      <iguideId>3899277</iguideId>
    </ids>
    <seriesIds i:nil="true"/>
    <masterTitle>Two and a Half Men</masterTitle>
    <secondaryTitle/>
    <episodeTitle i:nil="true"/>
    <category>Other</category>
    <color>Color</color>
    <lastAirDate i:nil="true"/>
    <originalAirDate>2003-09-22T00:00:00Z</originalAirDate>
    <programType>Series</programType>
    <releaseYear>2003</releaseYear>
    <duration>30</duration>
    <subcategory>comedy</subcategory>
    <syndicated>true</syndicated>
    <programLanguage>English</programLanguage>
    <partNumber i:nil="true"/>
    <partTotal i:nil="true"/>
    <streamable>1</streamable>
    <movieRating i:nil="true"/>
    <parentalRatings i:nil="true"/>
    <parentalRatingsUri>http://api.rovicorp.com/v1/video/parentalratings?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</parentalRatingsUri>
    <starRating i:nil="true"/>
    <tvRating>TV-14</tvRating>
    <mpaaRating i:nil="true"/>
    <cast i:nil="true"/>
    <castUri>http://api.rovicorp.com/v1/video/cast?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</castUri>
    <crew i:nil="true"/>
    <crewUri>http://api.rovicorp.com/v1/video/crew?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</crewUri>
    <awards i:nil="true"/>
    <awardsUri>http://api.rovicorp.com/v1/video/awards?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</awardsUri>
    <images i:nil="true"/>
    <imagesUri>http://api.rovicorp.com/v1/video/images?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</imagesUri>
    <clip i:nil="true"/>
    <clipUri i:nil="true"/>
    <seasons i:nil="true"/>
    <seasonsUri>http://api.rovicorp.com/v1/video/seasons?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</seasonsUri>
    <schedule i:nil="true"/>
    <scheduleUri>http://api.rovicorp.com/v1/video/schedule?duration=20160&amp;format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277&amp;serviceid=360861</scheduleUri>
    <event i:nil="true"/>
    <eventUri i:nil="true"/>
    <keywords i:nil="true"/>
    <keywordsUri>http://api.rovicorp.com/v1/video/keywords?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</keywordsUri>
    <moods i:nil="true"/>
    <moodsUri>http://api.rovicorp.com/v1/video/moods?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</moodsUri>
    <related i:nil="true"/>
    <relatedUri>http://api.rovicorp.com/v1/video/related?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</relatedUri>
    <review i:nil="true"/>
    <reviewUri i:nil="true"/>
    <synopsis i:nil="true"/>
    <synopsisUri>http://api.rovicorp.com/v1/video/synopsis?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</synopsisUri>
    <themes i:nil="true"/>
    <themesUri>http://api.rovicorp.com/v1/video/themes?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</themesUri>
    <tones i:nil="true"/>
    <tonesUri>http://api.rovicorp.com/v1/video/tones?format=xml&amp;apikey=4p1k3y&amp;cosmoid=3899277</tonesUri>
    <requestedId>7903</requestedId>
  </video>
</VideoDetail>


See Also

↑ Top

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/V1.MetaData.VideoService.Video:Info"
Personal tools