• Register

Program Metadata

Although program types can vary (seasonal episodes, specials, movies, football games), some common pieces of information are available for all program types. Additional fields may be returned for particular program types. See below for descriptions of common data and specialty fields.

Common Program Data

Field / object

Type

Notes

tmsId

string

14-character alphanumeric identifier for program record; first 2 characters generally identify program type (MV=movie, SH=show/series, EP=episode, SP=sports event EV=Theatre Event);
where available, parameter includeDetail=false will restrict program metadata to only programIds (tmsId, rootId, seriesId)

rootId

string

numeric identifier used to connect related program records with different title language, description language, and versions

title string program title; for episode records, this is series title
titleLang string language abbreviation code (e.g., 'en'=English, 'sp'=Spanish, 'pt-BR'=Brazilian Portugese);
see IETF Language Tag reference for more information
shortDescription string brief program description, Maximum 100 characters
longDescription string

long program description,  Maximum 1000 characters

descriptionLang string language abbreviation code (e.g., 'en'=English, 'sp'=Spanish, 'pt-BR'=Brazilian Portugese);
see IETF Language Tag reference for more information
genres string [ ] comma-separated list of program genres (e.g., Talk, News, Politics, Sports talk, Entertainment); returned in English
sourceType string Optional field, will provide information if the program is of a 'Local' or 'Network' source.
audience string indicates program target audience, derived from genres; one of two possible values: Children, Adults only 
recommendations Recommendation [ ] Top 3 TMS editorial recommendations, similar to given program *1 Retired
topCast string [ ] list of top three cast members, sorted by billingOrder ascending
(not present in program details, which gives full cast)
cast Credit [ ] program details only; full cast listing
crew Credit [ ] program details only; full crew listing
directors string [ ] comma-separated list of director names, formatted firstname<space>lastname
origAirDate date date of original TV airing; format is yyyy-mm-dd
releaseYear number year of release (primarily theatrical releases, but implemented for programs for consistency)
releaseDate date date of release (may be the same as origAirDate for TV programs) format is yyyy-mm-dd
preferredImage Image program image; if none found, generic image for program's entity type will be returned
awards Award [ ] list of award  nominations for program, with indicator for awards won
keywords Keywords [ ] program details only; TMS editorial selections in 6 key program description categories:
Character, Subject, Setting, Time Period, Mood, Theme | *1 Retired
holiday string program details only; text of holiday name related to program content
animation string program details only; animation type of program content; values may be:
Animated, Anime, Live action/animated, Live action/anime
entityType string program type; one of following values;
Show, Episode, Sports, Movie
subType string program subtype; one of following values:
Feature Film, Short Film, TV Movie, Miniseries, Series, Special, Sports event, Sports non-event, Paid Programming, Theatre Event, TBA, Off Air
ratings string ratings body and code (e.g., body=MPAA, code=PG-13); provided for US and Canadian ratings boards; rating at the program level is the original rating for the program, not rating at the airing level.
officialUrl string official movie or program website, if available

*1 - Keywords & Recommendation retirement (April 2021)

As communicated per customer notifications, Gracenote is planning to retire the Keywords and Recommendations datasets. Timeline

  • April 2021: Gracenote to stop assigning keywords and editorial recommendations to new Programs
  • July 2021: Gracenote to discontinue delivery of On Keywords and Editorial Recommendations

Series/Episode Program Metadata

Field / object

Type

Notes

seriesId string numeric identifier corresponding to rootId of series' main program record
episodeTitle string episode-specific title, maximum 150 characters
episodeImage Image for episodes only; episode-specific image (no text), where available
seasonNum number for episodes only; season number; will not be provided for non-seasonal shows such as soap operas
seasonYear number for episodes only; will be generated for series that have had a season YEAR provided by the source (and no ordinal season number) or according to Gracenote Standard for Series’ where episode number is provided but no season number is provided
episodeNum number for episodes only; episode number within season
totalSeasons string for series only; total number of seasons
total Episodes number for series only; total number of episodes across all seasons
runTime number

runTime’ represents actual content duration, excluding commercial content; output in ISO duration format (e.g., PT01H30M)

Movie Program Metadata

Field / object

Type

Notes

runTime number duration, specified in ISO-8601 format; PTxxHyyM = xx hours, yy minutes
qualityRating QualityRating
  • ratingsBody: critical reviewer; currently only TMS ratings provided, where available
  • value: numeric rating; TMS has a 1 - 4 star rating system (with 4 as best quality); possible values are 1, 1.5, 2, 2.5, 3, 3.5, 4

Sports Event Program Metadata

Field / object

Type

Notes

eventTitle string for team events, includes team names and location (e.g., Kansas at Missouri);
for non-team events, provides greater detail than common 'Title' field
organizationId string organization ID; indicates organization (NFL, NBA, etc) associated with teams; only available on team vs. team events
sportsId string sports ID; indicates general sport of event  (Basketball, Baseball, etc); only available on team vs. team events
gameDate string formatted yyyy-mm-dd
gameTime time formatted in local timezone for game; hh:mi:ss-<offset from UTC>; e.g., 13:00:00-05:00
gameTimeZone string timezone of game locale; e.g., Central Observing (if observing daylight savings time)
venue Venue
  • content: venue name (e.g., "Lucas Oil Stadium")
  • venueBrandId: resource identifier (e.g., "3928")
season Season
  • content: denotes year(s)  (e.g., "2012", "2011-2012")
  • type: regular or pre/post season (e.g., "Pre", "Reg", "Post")
teams Team [ ]
  • name: team name (e.g., Kansas)
  • teamBrandId: resource identifier
  • isHome: boolean indicator when team playing at home venue

Example 1 - Episode Program Record


{
  "tmsId": "EP015314270020",
  "rootId": "9362638",
  "seriesId": "9085357",
  "title": "The Countdown",
  "titleLang": "en",
  "shortdescription": "A countdown of the best Clint Eastwood films shows the actor as: a gunslinger, a disc jockey.",
  "longDescription": "A countdown of the best Clint Eastwood films shows the actor as: an Old West gunslinger, a boxing coach, a war vet, a prison escapee, and a disc jockey.",
  "descriptionLang": "en",
  "subType": "Series",
  "genres": ["Entertainment"],
  "origAirDate": "2012-08-09",
  "preferredImage": {
    "uri": "tvbanners/v5/AllPhotos/9085357/p9085357_b_v5_aa.jpg",
    "height": "360",
    "width": "240",
    "primary": "true",
    "category": "Banner"
  },
  "episodeTitle": "Clint Eastwood",
  "seasonNum": 1,
  "episodeNum": 20,
  "entityType": "Episode"
}

Example 2 - Movie Program Record


{
  "tmsId": "MV003331980000",
  "rootId": "8288118",
  "title": "Battle: Los Angeles",
  "titleLang": "en",
  "shortDescription": "A Marine officer (Aaron Eckhart) and his platoon make a daring stand against alien invaders.",
  "longDescription": "For many years, humans have reported various UFO sightings around the world, fueling speculation about the existence of life on other worlds. In 2011, mankind learns the truth the hard way when alien invaders attack. One by one, the world's great cities fall, leaving Los Angeles as the battleground for humanity's last stand. It's up to a Marine staff sergeant (Aaron Eckhart) and his platoon to draw a line in the sand against a powerful enemy unlike any previously encountered.",
  "descriptionLang": "en",
  "subType": "Feature Film",
  "ratings": [
  {
    "body": "Alberta's Film Classification Board",
    "code": "14A"
  },
  {
    "body": "Departamento de Justiça, Classificação, Títulos e Qualificação",
    "code": "14"
  },
  {
    "body": "Motion Picture Association of America",
    "code": "PG-13"
  },
  ...additional ratings...
],
  "genres": ["Science fiction","Action"],
  "preferredImage": {
    "uri": "assets/p8288118_p_v5_aa.jpg",
    "height": "360",
    "width": "240",
    "primary": "true",
    "category": "Poster Art",
    "caption": {
      "content": "Battle: Los Angeles (2011)",
      "lang": "en"
    }
  },
  "releaseYear": 2011,
  "qualityRating": {
    "ratingsBody": "TMS",
    "value": "2"
  },
  "officialUrl": "http://www.battlela.com/",
  "advisories": ["Adult Language","Violence","Adult Situations"],
  "cast": [{
    "personId": "73023",
    "nameId": "73023",
    "name": "Aaron Eckhart",
    "role": "Actor",
    "characterName": "Ssgt. Michael Nantz",
    "billingOrder": "01"
  },
  {
    "personId": "219616",
    "nameId": "222033",
    "name": "Michelle Rodriguez",
    "role": "Actor",
    "characterName": "Tsgt. Elena Santos",
    "billingOrder": "02"
  },
  {
    "personId": "52901",
    "nameId": "52901",
    "name": "Ramon Rodriguez",
    "role": "Actor",
    "characterName": "2nd Lt. William Martinez",
    "billingOrder": "03"
  },
  ...additional cast...
  ],
  "crew": [{
    "personId": "267211",
    "nameId": "270791",
    "name": "Jonathan Liebesman",
    "role": "Director",
    "billingOrder": "01"
  },
  {
    "personId": "341476",
    "nameId": "350350",
    "name": "Chris Bertolini",
    "role": "Screenwriter",
    "billingOrder": "02"
  },
  {
    "personId": "274004",
    "nameId": "318356",
    "name": "Neal H. Moritz",
    "role": "Producer",
    "billingOrder": "03"
  },
  ...additional crew...
  ],
  "directors": ["Jonathan Liebesman"],
  "runTime": "PT01H56M",
  "entityType": "Movie"
}

Example 3 - Sports Event Program Record


{
  "tmsId": "SP002900240000",
  "rootId": "10298347",
  "seriesId": "191276",
  "title": "NBA Basketball",
  "titleLang": "en",
  "shortDescription": "From Barclays Center in Brooklyn, N.Y.",
  "longDescription": "From Barclays Center in Brooklyn, N.Y.",
  "descriptionLang": "en",
  "genres": ["Basketball"],
  "eventTitle": "Miami Heat at Brooklyn Nets",
  "subType": "Sports event",
  "gameDate": "2014-01-10",
  "gameTime": "20:00:00-05:00",
  "gameTimeZone": "Eastern Observing",
  "organizationId": "19",
  "sportsId": "59",
  "teams": [
    {"name": "Miami Heat", "teamBrandId": "414"},
    {"name": "Brooklyn Nets", "isHome": true, "teamBrandId": "7277"}
  ],
  "venue": {
    "content": "Barclays Center",
    "venueBrandId": "1257"
  },
  "season": {
    "content": "2013-2014",
    "type": "Reg"
  },
  "preferredImage": {
    "uri": "assets/p191276_b_v5_aa.jpg",
    "height": "360",
    "width": "240",
    "primary": "true",
    "category": "Banner-L3",
    "tier": "Sport"
  },
  "entityType": "Sports"
}