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 ...
]