Advance planner
/programs/advancePlanner
Returns a list of notable programming and associated metatdata due to air at future date. This includes programming such as holiday specials, notable sporting events, series premieres, returning shows premieres, finales, and movies appearing on TV for the first time. See eventCode below for full list of programming types.
Response data will be sorted by air date, with partial dates sorted after full dates.
Request Parameters
| Parameter | Mandatory? | Description |
| startDate | Yes | Start date, must be current day or greater. Format yyyy-mm-dd. |
| endDate | No | End date, must be greater than startDate. No maximum, although most advance planner events are within 365 days. Defaults to 31 days past startDate. Format yyyy-mm-dd. |
| eventCode | No | Comma-separated list of event types to return; default will return all types Numeric codes for use in request: 1 - Holiday Special 2 - Network Premiere of Movie on TV 3 - Notable Episode 4 - Returning with New Episodes 5 - Season Premiere 6 - Season Finale 7 - Series Premiere 8 - Series Finale 9 - Special 10 - Sporting Event 11 - TV Movie Premiere |
| 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). If program description not available in specified language, primary TMS ID will be returned regardless of description language. If not specified, preference defaults to English. |
| 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. |
| api_key | Yes | 24-character key obtained during application registration |
Response Body
|
Response |
Description |
| airDate | Planned air date; full or partial date string, formatted yyyy-mm-dd or yyyy-mm or yyyy; full dates sorted before partial dates, within year/month blocks |
| eventCode | Specifies type of programming; corresponds to types in eventCode parameter selection |
| releaseNotes | Programming notes; may include guest star notes or other comments explaining show notability |
| lastUpdate | Last TMS editorial update; ISO-8601 format |
| program | Program metadata as follows: |
| tmsId | TMS-generated 14-character alphanumeric identifier for program record; first 2 characters generally identify program type (MV=movie, SH=show/series, EP=episode, SP=sports event) |
| title | program title; for episode records, this is series title |
| titleLang | 2-letter language abbreviation code (e.g., 'en'=English, 'sp'=Spanish) |
| shortDescription |
program description, maximum 100 characters |
| longDescription |
program description, maximum 1000 characters |
| descriptionLang |
2-letter language abbreviation code (e.g., 'en'=English, 'sp'=Spanish) |
| genres | comma-separated list of program genres (e.g., Romance, Comedy, News) |
| topCast | comma-separated list of top 3 cast member names, in billing order; if available |
| directors | comma-separated list of director names |
| ratings | ratings body and code, if available |
| origAirDate | also known as OAD, date of original TV airing; format is yyyy-mm-dd |
| preferredImage | program image, if available; see Image Metadata for details |
| episodeTitle | episodes only; episode-specific title |
| seasonNum | episodes only; season number; will not be provided for non-seasonal shows such as soap operas |
| episodeNum | episodes only; episode number within season |
| releaseYear | movies only; theatrical release year |
| entityType | type of program: show, episode, sports, movie |
Sample Request
Return information for lineupId acquired by calling /lineups.
http://data.tmsapi.com/v1.1/programs/advancePlanner?startDate=2015-02-15&api_key=1234567890
Sample Response
[
{
"program":{
"tmsId":"EP003803410375",
"rootId":"11410543",
"seriesId":"184657",
"subType":"Series",
"title":"CSI: Crime Scene Investigation",
"episodeTitle":"Under My Skin; The End Game",
"origAirDate":"2015-02-15",
"titleLang":"en",
"descriptionLang":"en",
"entityType":"Episode",
"genres":[ "Crime drama", "Action", "Suspense", "Mystery" ],
"longDescription":"A murder has ties to the disappearance of two teenage girls; the Gig Harbor killer's motives are revealed in a final showdown; Stokes makes a fateful decision.",
"shortDescription":"A murder has ties to the kidnapping of two teenage girls; a killer's motives are revealed.",
"episodeNum":17,
"seasonNum":15,
"topCast":[ "Ted Danson", "Elisabeth Shue", "George Eads" ],
"directors":[ "Alrick Riley" ],
"ratings":[ { "code":"TV14", "body":"USA Parental Rating" } ],
"preferredImage":{
"width":"240",
"height":"360",
"uri":"assets/p184657_b_v5_aa.jpg",
"category":"Banner-L1",
"text":"yes",
"primary":"true",
"tier":"Series"
}
},
"airDate":"2015-02-15",
"lastUpdate":"2015-01-09T00:43:49",
"eventCode":"Season Finale"
},
{
"program":{
"tmsId":"EP004443830613",
"rootId":"11419876",
"seriesId":"183890",
"subType":"Series",
"title":"Saturday Night Live",
"episodeTitle":"SNL 40th Anniversary Special",
"origAirDate":"2015-02-15",
"titleLang":"en",
"descriptionLang":"es",
"entityType":"Episode",
"genres":[ "Comedy" ],
"longDescription":"Las más grandes estrellas de la comedia, los anfitriones pasados, los miembros del elenco y leyendas de la música rinden homenaje a los 40 años de \" Saturday Night Live.",
"shortDescription":"Las más grandes estrellas de la comedia, rinden homenaje a los 40 años de \"Saturday Night Live.\"",
"topCast":[ "Kenan Thompson", "Kate McKinnon", "Vanessa Bayer" ],
"ratings":[ { "code":"TV14", "body":"USA Parental Rating" } ],
"preferredImage":{
"width":"240",
"height":"360",
"uri":"assets/p183890_b_v5_ab.jpg",
"category":"Banner-L1",
"text":"yes",
"primary":"true",
"tier":"Series"
}
},
"airDate":"2015-02-15",
"lastUpdate":"2015-01-30T13:13:24",
"releaseNotes":"Celebrating 40 years of the show.",
"eventCode":"Notable Episode"
},
{
"program":{
"tmsId":"SH018946960000",
"rootId":"10646032",
"seriesId":"191276",
"organizationId":"19",
"sportsId":"59",
"subType":"Sports event",
"title":"2015 NBA All-Star Game",
"titleLang":"en",
"descriptionLang":"en",
"entityType":"Show",
"genres":["Basketball"],
"longDescription":"The NBA's midseason showcase featuring 24 of the league's brightest stars with the starters selected by the fans and reserves chosen by the coaches. From Madison Square Garden in New York.",
"shortDescription":"The NBA's midseason showcase featuring 24 of the league's brightest stars.",
"preferredImage":{
"width":"240",
"height":"360",
"uri":"assets/p10646032_b_v5_aa.jpg",
"category":"Banner-LO",
"text":"yes",
"primary":"true",
"tier":"Sport"
}
},
"airDate":"2015-02-15",
"lastUpdate":"2014-10-09T03:19:56",
"eventCode":"Sporting Event"
},
... additional programs ...
]