Tools
Video/Images
Returns movie and television program images.
A video/images request returns images in order of image type as shown in the Image Order table. Images within each type are sorted by width, from narrow to wide. If the specified show is an episode in a series, then episode images appear before images of the series master.
This request may return a large amount of data. To speed data transmission, do the following:
- Request one page of data at a time, requesting only what you want to immediately display.
- Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
Syntax
| video/images? | video=video cosmoid=cosmoid iguideid=iguideid |
&apikey=apikey&sig=sig [&format=format] [&offset=offset] [&count=count] [&country=country] [&language=language] |
Request Example 1
- Request images from The Simpsons television series.
Request Example 2
- Request the first two images from the The Simpsons Movie.
Request Example 3
- Request the first two images from the The Simpsons Movie in an XML response.
http://api.rovicorp.com/data/v1/video/images?apikey=apikey&sig=sig&cosmoid=6941396&count=2&
format=xml
format=xml
Request Parameters
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:
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:
| |
| 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 | 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:
| |
| count | No | Number of items to be returned. The default is zero, which returns all items after the offset.
Use count and offset to paginate the response. | |
| country | No | Country of the language of the response. The current release of the API supports only US. | |
| format | No | Format of the returned data: json or xml. The default is JSON. | |
| language | No | Language of the response data. This request supports only en (English). | |
| offset | No | Number of items at the start of the returned list to skip. The default is zero.
Use count and offset to paginate the response. |
Response
Response Header
| 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. |
| parentIds | parentIds | All of the IDs for the requested movie or program that are recognized by the Video Service. |
| 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. |
| view | view | Summary of items returned in a list of items. |
Response for Video/Images
| Response | Type | Description |
|---|---|---|
| images | Image [ ] | URLs to images of the movie or program specified in the request, along with information about the images.
The sequence of images is by image type as shown in the Image Order table. Images within each type are sorted by width, from narrow to wide. If the specified show is an episode in a series, then episode images appear before images of the series master. |
JSON Response Example
- Here's the response to Request Example 2, showing the first two of 446 images. The response is formatted with extra spaces and carriage returns to make it easy to read.
{
"status":"ok",
"code":200,
"messages":null,
"build":"1.6.1.12",
"parameters":{
"apiKey":"4p1k3y",
"id":"6941396",
"offset":0,
"count":2
},
"view":{
"offset":0,
"count":2,
"total":446
},
"serverName":"tul1cstw2",
"startTime":"2011-08-04T00:02:10.8600519Z",
"endTime":"2011-08-04T00:02:11.3288109Z",
"duration":468,
"parentIds":{
"cosmoId":"6941396"
},
"images":[
{
"height":300,
"width":200,
"formatid":0,
"url":"http:\/\/actual-url-concealed.jpg",
"author":null,
"copyrightOwner":null
},
{
"height":500,
"width":333,
"formatid":16,
"url":"http:\/\/actual-url-concealed.jpg",
"author":null,
"copyrightOwner":null
}
]
}
"status":"ok",
"code":200,
"messages":null,
"build":"1.6.1.12",
"parameters":{
"apiKey":"4p1k3y",
"id":"6941396",
"offset":0,
"count":2
},
"view":{
"offset":0,
"count":2,
"total":446
},
"serverName":"tul1cstw2",
"startTime":"2011-08-04T00:02:10.8600519Z",
"endTime":"2011-08-04T00:02:11.3288109Z",
"duration":468,
"parentIds":{
"cosmoId":"6941396"
},
"images":[
{
"height":300,
"width":200,
"formatid":0,
"url":"http:\/\/actual-url-concealed.jpg",
"author":null,
"copyrightOwner":null
},
{
"height":500,
"width":333,
"formatid":16,
"url":"http:\/\/actual-url-concealed.jpg",
"author":null,
"copyrightOwner":null
}
]
}
XML Response Example
- Here's the response to Request Example 3.
<VideoImages 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.6.1.12</build>
<parameters>
<apiKey>4p1k3y</apiKey>
<id>6941396</id>
<offset>0</offset>
<count>2</count>
<format>xml</format>
</parameters>
<view>
<offset>0</offset>
<count>2</count>
<total>446</total>
</view>
<serverName>tul1cstw1</serverName>
<startTime>2011-08-04T00:01:01.1451109Z</startTime>
<endTime>2011-08-04T00:01:01.9419859Z</endTime>
<duration>796</duration>
<parentIds>
<cosmoId>6941396</cosmoId>
</parentIds>
<images>
<Image>
<height>300</height>
<width>200</width>
<formatid>0</formatid>
<url>http://actual-url-concealed.jpg</url>
<author i:nil="true"/>
<copyrightOwner i:nil="true"/>
</Image>
<Image>
<height>500</height>
<width>333</width>
<formatid>16</formatid>
<url>http://actual-url-concealed.jpg</url>
<author i:nil="true"/>
<copyrightOwner i:nil="true"/>
</Image>
</images>
</VideoImages>
<status>ok</status>
<code>200</code>
<messages i:nil="true"/>
<build>1.6.1.12</build>
<parameters>
<apiKey>4p1k3y</apiKey>
<id>6941396</id>
<offset>0</offset>
<count>2</count>
<format>xml</format>
</parameters>
<view>
<offset>0</offset>
<count>2</count>
<total>446</total>
</view>
<serverName>tul1cstw1</serverName>
<startTime>2011-08-04T00:01:01.1451109Z</startTime>
<endTime>2011-08-04T00:01:01.9419859Z</endTime>
<duration>796</duration>
<parentIds>
<cosmoId>6941396</cosmoId>
</parentIds>
<images>
<Image>
<height>300</height>
<width>200</width>
<formatid>0</formatid>
<url>http://actual-url-concealed.jpg</url>
<author i:nil="true"/>
<copyrightOwner i:nil="true"/>
</Image>
<Image>
<height>500</height>
<width>333</width>
<formatid>16</formatid>
<url>http://actual-url-concealed.jpg</url>
<author i:nil="true"/>
<copyrightOwner i:nil="true"/>
</Image>
</images>
</VideoImages>