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