Series episodes

/series/:seriesId/episodes

Returns detailed metadata for episodes within a specified series. Season number can be optionally specified to limit return data.
Note that v1.1 response will return a maximum of 100 episodes.  Paging parameter (limit and offset) can be used to retrieve all episodes in configurable batches.  If paging parameters not supplied, response format matches v1.  If paging parameters specified (limit/offset), response will be similar to Program Search response, with hitCount indicating total episodes, and hits object holding search results. 

The preferredImage is representative season or series image. Unique episodic images are available for some series; where available, these are found in new episodeImage field.

Response will be sorted according to season and episode, in ascending order.

Request Parameters

Parameter

Mandatory?

Description

seriesId

Yes

seriesId, which can be retrieved by calling /programs API.

season

No

Season number to limit episodes returned;
if not specified, all episodes for all seasons will be returned, up to a maximum of 100.

limit No The maximum number of programs to be returned from the query.
offset No Indicates starting point of response (zero-based index).  Used in conjunction with limit to page through results. 
For example, offset=10 will position results to begin with 11th hit.
If not specified, defaults to 0 to start resultset at beginning.
size No Amount of program metadata to be returned. The default value is Detailed. For smaller response size, use Basic.

imageSize

No

Valid values are: Sm, Md, Lg, Ms. See Image Sizing for details.
If not specified, defaults to Md.
If requested image size is not available, generic image will be returned.

imageAspectTV

No

Requested aspect ratio (horizontal by vertical) for TV show images
Valid values are: 2x3, 3x4, 4x3, 16x9
If not specified, defaults to 2x3
If requested aspect ratio is not available, generic image will be returned.

imageText

No

Boolean indicating preference for image types with text (banners) or without text (iconics). If requested preference is not available, image selection will continue to next type (banner/iconic), before finally returning generic if no image found. Defaults to true for text preference.

titleLang No Filter results based on the specified title language. Use IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). If not specified, defaults to 'en'.

descriptionLang

No

Specify description language preference using IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). For each epsiode, if program description not available in specified language, primary TMS ID for that episode will be returned regardless of description language. If not specified, preference defaults to English.

api_key

Yes

24-character key obtained during application registration

Response Body

Response

Type

Description

Program collection 

Program [ ]

Detailed information regarding episodes belonging to specified series.

Sample Request 1 - without paging

http://data.tmsapi.com/v1.1/series/8981323/episodes?season=1&api_key=1234567890

Sample Response

[
  {
    "tmsId":"EP015084700001",
    "rootId":"9120854",
    "seriesId":"8981323",
    "subType":"Series",
    "title":"Anger Management",
    "episodeTitle":"Charlie Goes Back to Therapy",
    "origAirDate":"2012-06-28",
    "titleLang":"en",
    "descriptionLang":"en",
    "entityType":"Episode",
    "genres":["Sitcom"],
    "longDescription":"Charlie, a baseball player with anger issues decides to return to therapy after a bad run-in with his ex-wife's new boyfriend.",
    "shortDescription":"Charlie decides to return to therapy after a bad run-in with his ex-wife's new boyfriend.",
    "episodeNum":1,
    "seasonNum":1,
    "topCast":[ "Charlie Sheen", "Selma Blair", "Shawnee Smith" ], 
    "ratings":[ { "code":"TV14", "body":"USA Parental Rating" } ],
    "preferredImage":{
      "width":"240",
      "height":"360",
      "uri":"assets/p8981323_b_v5_ae.jpg",
      "category":"Banner-L1",
      "text":"yes",
      "primary":"true",
      "tier":"Series"
    }
  },
  {
    "tmsId":"EP015084700002",
    "rootId":"9271054",
    "seriesId":"8981323",
    "subType":"Series",
    "title":"Anger Management",
    "episodeTitle":"Charlie and the Slumpbuster",
    "origAirDate":"2012-06-28",
    "titleLang":"en",
    "descriptionLang":"en",
    "entityType":"Episode",
    "genres":["Sitcom"],
    "longDescription":"The new Charlie deals with a ghost from his baseball-playing days when an unattractive woman he slept with shows up as a new patient.",
    "shortDescription":"Charlie deals with a ghost from his baseball days when a woman he slept with shows up as a patient.",
    "episodeNum":2,
    "seasonNum":1,
    "topCast":[ "Charlie Sheen", "Selma Blair", "Shawnee Smith" ], 
    "ratings":[ { "code":"TV14", "body":"USA Parental Rating" } ],
    "preferredImage":{
      "width":"240",
      "height":"360",
      "uri":"assets/p8981323_b_v5_ae.jpg",
      "category":"Banner-L1",
      "text":"yes",
      "primary":"true",
      "tier":"Series"
    }
  },
  ... additional episodes ...
]