Video/Seasons
Returns links to information about seasons and episodes in a television series. An optional argument returns season information in the response instead of a link to the information.
A request with an episode ID returns information about the season the episode is in.
A request with a series ID returns links to all seasons in the series in reverse order, with the latest season first. If, however, the database contains episodes that have not been assigned to a season—unsequenced episodes—those episodes are labeled season 0 and that link is returned first.
The links returned are:
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/seasons? |
video=video cosmoid=cosmoid iguideid=iguideid |
&apikey=apikey&sig=sig [&format=format] [&offset=offset] [&count=count] [&country=country] [&language=language] [&include=include] |
Request Example 1
- Request links to information about all seasons and all episodes of House M.D.
Request Example 2
- Request the last two seasons listed for House M.D.
Request Example 3
- Request the last two seasons listed for House M.D. and include the season information.
Request Example 4
- Return the response to Request Example 3 in XML format.
Request Example 5
- Request season information for an episode of The Simpsons.
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:
- 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 television series or episode in a 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 or episode 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:
|
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:
|
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. |
include | No | Specify include=all to include season information in the response instead of URLs to season information. |
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 | 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/Seasons
Response | Type | Description |
number | VideoSeason [ ] | Links to season and episode information for the television series as specified in the request. |
Response Example 1
- Here's the response to Request Example 2. It 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":"4180581",
"offset":0,
"count":2
},
"view":{
"offset":0,
"count":2,
"total":8
},
"serverName":"tul1cstw4",
"startTime":"2011-08-04T23:40:11.4588852Z",
"endTime":"2011-08-04T23:40:12.1776122Z",
"duration":718,
"parentIds":{
"cosmoId":"4180581"
},
"seasons":[
{
"number":"0",
"episodesUri":"http:\/\/api.rovicorp.com\/v1\/video\/season\/0\/info?format=json&apikey=4p1k3y&cosmoid=4180581"
},
{
"number":"7",
"seasonInfoUri":"http:\/\/api.rovicorp.com\/v1\/video\/season\/7\/info?format=json&apikey=4p1k3y&cosmoid=4180581",
"episodesUri":"http:\/\/api.rovicorp.com\/v1\/video\/season\/7\/episodes?format=json&apikey=4p1k3y&cosmoid=4180581"
}
]
}
Response Example 2
- Here's the response to Request Example 3, which includes the include=all parameter.
{
"status":"ok",
"code":200,
"messages":null,
"build":"1.6.1.12",
"parameters":{
"apiKey":"4p1k3y",
"id":"4180581",
"offset":0,
"count":2,
"include":"all"
},
"view":{
"offset":0,
"count":2,
"total":8
},
"serverName":"tul1cstw1",
"startTime":"2011-08-04T23:42:22.3414857Z",
"endTime":"2011-08-04T23:42:23.1539857Z",
"duration":812,
"parentIds":{
"cosmoId":"4180581"
},
"seasons":[
{
"number":"0",
"title":"Unsequenced",
"totalEpisodes":46,
"episodesUri":"http:\/\/api.rovicorp.com\/v1\/video\/season\/0\/info?format=json&apikey=4p1k3y&cosmoid=4180581"
},
{
"number":"7",
"title":"Season 7",
"start":"2010",
"end":"2011",
"totalEpisodes":23,
"ids":{
"amgMovieId":null,
"cosmoId":"17971804"
},
"episodesUri":"http:\/\/api.rovicorp.com\/v1\/video\/season\/7\/episodes?format=json&apikey=4p1k3y&cosmoid=4180581",
"parentalRatings":[
],
"associatedMedia":[
],
"streamable":1
}
]
}
XML Response Example 1
- Here's the response to Request Example 4, which includes the include=all parameter.
<VideoSeasons 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>4180581</id>
<offset>0</offset>
<count>2</count>
<include>all</include>
<format>xml</format>
</parameters>
<view>
<offset>0</offset>
<count>2</count>
<total>8</total>
</view>
<serverName>tul1cstw2</serverName>
<startTime>2011-08-04T23:44:00.4586164Z</startTime>
<endTime>2011-08-04T23:44:00.9898766Z</endTime>
<duration>531</duration>
<parentIds>
<cosmoId>4180581</cosmoId>
</parentIds>
<seasons>
<VideoSeason>
<number>0</number>
<title>Unsequenced</title>
<totalEpisodes>46</totalEpisodes>
<episodesUri>http://api.rovicorp.com/v1/video/season/0/info?format=xml&apikey=4p1k3y&cosmoid=4180581</episodesUri>
</VideoSeason>
<VideoSeason>
<number>7</number>
<title>Season 7</title>
<start>2010</start>
<end>2011</end>
<totalEpisodes>23</totalEpisodes>
<ids>
<amgMovieId i:nil="true"/>
<cosmoId>17971804</cosmoId>
</ids>
<episodesUri>http://api.rovicorp.com/v1/video/season/7/episodes?format=xml&apikey=4p1k3y&cosmoid=4180581</episodesUri>
<parentalRatings/>
<associatedMedia/>
<streamable>1</streamable>
</VideoSeason>
</seasons>
</VideoSeasons>
XML Response Example 2
- Here's the response to Request Example 5, which includes the include=all parameter.
<VideoSeasons 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.0.1</build>
<parameters>
<apiKey>4p1k3y</apiKey>
<id>7840643</id>
<include>all</include>
<format>xml</format>
</parameters>
<view>
<total>1</total>
</view>
<serverName>tul1cstw4</serverName>
<startTime>2011-08-11T22:33:55.1492656Z</startTime>
<endTime>2011-08-11T22:33:55.1961391Z</endTime>
<duration>46</duration>
<parentIds>
<cosmoId>7840643</cosmoId>
</parentIds>
<seasons>
<VideoSeason>
<number>20</number>
<title>Season 20</title>
<start>2008</start>
<end>2009</end>
<totalEpisodes>22</totalEpisodes>
<ids>
<amgMovieId i:nil="true"/>
<cosmoId>13378115</cosmoId>
<iguideId i:nil="true"/>
</ids>
<episodesUri>http://api.rovicorp.com/v1/video/season/20/episodes?format=xml&apikey=4p1k3y&cosmoid=7840643</episodesUri>
<parentalRatings/>
<associatedMedia/>
<streamable>1</streamable>
</VideoSeason>
</seasons>
</VideoSeasons>
See Also
↑ Top