Programs Endpoint

The Programs  endpoint  is designed to provide Gracenote TV and movie program information, organized by industry-standard TMSId for language-specific representation of programs.

The Programs schema provides rich metadata for both movies and TV programs, including:

  • TMSId, for language-specific representation of program and use with Schedules API
  • Titles and descriptions
  • Full cast and crew, identified by personId for linking with celeb details in Celebrity API
  • Award nominations and wins
  • International ratings
  • Release information by country
  • Season information, including dates and images
  • Image references for use with Media Cloud
  • Video Descriptors for more detailed information about

All programs are marked with a unique updateId, denoting current dataset for program. Changes to program data will result in assignment of a new updateId, which allows you to pull deltas since last retrieval, instead of ingestion for full program dataset for refresh. Scope of programs can be requested by schedule relevancy, language, or combination of criteria, dependent on customer need.

Programs

This section provides information about the On API Program identifiers, hierarchy, types, as well as general properties (genres, ratings, releases, relationships) and key fields.

Data Structure and Relationships

The Programs XSD schema file is located here:

http://files.api.gracenote.com/xsd/on_update_programs_3.22.xsd

Unless stated otherwise, the XPATH in the tables below is relative to on/programs/program/

Identifiers, Language and Title Variants

XPATH Element/Attribute Description ID Space
@TMSId Gracenote unique identifier for the program variant TMSId
@rootId Gracenote unique identifier for the program variant group rootId
@connectorId TMSId of episode’s parent series program TMSId
@seriesId RootId of episode’s parent series program rootId
@seasonId Season “rootId” rootId
@versionId Movie versionId versionId

TMSId is an alphanumeric identifier for the Programs object - a unique metadata variant of a television program.

XPATH Element/Attribute Description Example
titles/@lang Program titles language en, en-GB, fr-CA, de, es
descriptions/@lang Program descriptions language en, en-GB, fr-CA, de, es
titles/title/@subType Program title subType Main, AKA, Promotional, IMAX, 3D

 

The TMSId is used to represent variants of the same program with different title/description languages, or different title variations (title_lang / desc_lang / title_subType):

Several different types of papers Description automatically generated

 

The rootId is a numeric identifier that connects all metadata/title variants (TMSIds) of the same program (movie, episode, series, special or sports event) - further also referred to as “work”. Occasionally, a program can have variations that exist under different rootIds, in which case the respective sets of programs are typically connected via the program relationship link (see Program Relationships section for details).

Movie programs have an additional identifier (versionId) distinguishing different movie versions (such as theatrical version vs director’s cut) under the same rootId. The versionId is not an index in a controlled vocabulary indicating the version type, but rather an identifier similar to the rootId that distinguishes work variants at a more granular (version) level. The versions can differ from one another in any of the following: runtime, rating, color; separate versions are also created for IMAX and/or 3D titles.

Examples of movies with identifiers and language/subType values:

TMSId rootId versionId title lang desc lang title subType title
MV000118140000 6252 6639 en en Main 2001: A Space Odyssey
MV000310470000 6252 6639 fr-CA fr-CA AKA 2001, l'odyssée de l'espace
MV000691150000 6252 6639 en es Main 2001: A Space Odyssey
MV000691160000 6252 6639 es es AKA 2001: Odisea del espacio
MV002514040000 6252 6639 pt-BR pt-BR AKA 2001: Uma Odisseia no Espaço
MV011825150000 6252 11361997 en en IMAX 2001: A Space Odyssey -- The IMAX 2D Experience
MV001640710000 5588 5945 en en AKA Seven Samurai
MV001835140000 5588 5945 en en AKA The Magnificent Seven
MV015980970000 5588 5945 ja ja Main 七人の侍
MV000070860000 4190 4474 en en Main Blade Runner
MV008498820000 4190 4473 en en Promotional Blade Runner: Director's Cut
MV002070550000 4190 173339 en en Promotional Blade Runner: The Final Cut

Generally speaking, given multiple programs’ TMSIds or versionIds for the same root, Gracenote does not prescribe what the representative or “canonical” variant should be, because it usually depends on the specific use case. For some use cases such as universal search or aggregated catalog views, it may become necessary to represent each work with a single program.

Series Hierarchy

Episode programs are linked to parent Series programs using connectorId as well as seriesId and seasonId. Episodes can be episodes of a series, or sporting events that are part of a specific league or competition represented by the Series program.

While seriesId links any/all Episodes in the series to the Series root, the connectorId connects the Episode TMSIds/programs with specific title language / description language / title subtype combination to the corresponding Series TMSId/program (connector). These collections will be further referred to as Series (language) variants - they generally differ in metadata language but there can also be title variations within the same language.

A diagram of a series root system Description automatically generated

The table below lists sample Series and Episode programs for the en/en/Main variant of “Friends”. Other variants will have the same root, series and season identifiers, but the TMSIds and connectorIds will be different.

TMSId rootId connectorId seriesId seasonId S#E# title or episode title
SH001151270000 183931 SH001151270000 183931     Friends
EP001151270001 1712253 SH001151270000 183931 7892576 S1E1 Pilot
EP001151270004 1712255 SH001151270000 183931 7892576 S1E2 The One With the Sonogram at the End
EP001151270002 1712254 SH001151270000 183931 7892576 S1E3 The One With the Thumb
EP001151270027 1712277 SH001151270000 183931 7892599 S2E1 The One With Ross' New Girlfriend
EP001151270028 1712278 SH001151270000 183931 7892599 S2E2 The One With the Breast Milk
EP001151270029 1712279 SH001151270000 183931 7892599 S2E3 The One Where Heckles Dies

Seasons are not represented by separate program objects (with the partial exception of superseries, see below); instead, the season information is contained within the Series program object (connector) and labeled with the seasonId which is also referenced by the Episode programs belonging to the Season. Episodes may or may not reference/belong to a Season. The seasonId for a given season (say, S1) is the same for all Series programs with a given root - it is like rootId in that it’s not differentiated by the metadata language - however, each Series language variant program will carry (partial) season data that is specific to that variant.

The Series structure in the specific variant (title language / description language / title subtype combination) may or may not be complete. Conversely, there are cases when Series variants contain duplicate sets of Episodes and disambiguation/filtering may be required to derive consistent and unique episode sequences.

Sports programs follow the same approach for the event-series hierarchy, with the exception of the season aspect - the sports season information is stored elsewhere and the seasonId is not used. Also, Sports and Series program typing is different (see Program Types sections below).

TMSId rootId connectorId seriesId seasonId title or episode title
SH049241660000 191273 SH049241660000 191273   MLB Baseball
EP049241660034 26141996 SH049241660000 191273   Boston Red Sox at Atlanta Braves
EP049241660128 26142559 SH049241660000 191273   St. Louis Cardinals at Houston Astros
EP049241660129 26142560 SH049241660000 191273   Pittsburgh Pirates at Detroit Tigers
EP049241660182 26142815 SH049241660000 191273   Milwaukee Brewers at Cincinnati Reds

Superseries

Series can be further grouped into “superseries” whereas the seriesId of the Episodes and of their immediate Series parent will point to the rootId of the Superseries. Superseries may also have its own Episodes. There should be only one grouping level in the Superseries.

Superseries arrangement is often used in sports programs to break out the final competition Series from the main / regular season game Series. It is also used in cases when the Series contains Seasons whose title is different from the main / original Series title. The “sub-series” programs in this arrangement may contain one or multiple Seasons of the Superseries.

A close-up of several papers Description automatically generated

TMSId rootId connectorId seriesId S## title or episode title
SH000031280000 191277 SH000031280000 191277   NFL Football
EP000031284393 26058022 SH000031280000 191277   Houston Texans at Baltimore Ravens
SH049253000000 26058095 SH049253000000 191277   2024 Super Bowl
EP049253000001 26058116 SH049253000000 191277   San Francisco 49ers vs. Kansas City Chiefs
SH014661780000 8807210 SH014661780000 8807210 1 American Horror Story
SH016052660000 9423797 SH016052660000 8807210 2 American Horror Story: Asylum
SH017774000000 10127873 SH017774000000 8807210 3 American Horror Story: Coven
SH015997530000 9400970 SH015997530000 9400970 1,3,4 Dragons: Riders of Berk
SH017764160000 10124235 SH017764160000 9400970 2 Dragons: Defenders of Berk

Program Types

The Gracenote program typing provides categorical classification of the program - theatrical films can be differentiated from TV movies or short films, series from episodes or short extras, current season sports series/events - from legacy sports series/events. The subType is the main element that identifies the type of the program while the progType provides additional context for Episodes as well as Sports related programs.

XPATH Element/Attribute Description Example
progType/ Gracenote Program Type Feature Film, Series, Sports event
subType/ Gracenote Program subType Feature Film, Series, Episode, Team Event

Some of the notable progType / subType combinations are listed in the table below.

progType subType Description Example
Feature Film Feature Film A full length movie (40+ min) 2001: A Space Odyssey
TV Movie TV Movie A movie made for TV High School Musical
Short Film Short Film A short movie under 40 min When Billie Met Lisa
Series Series Programs produced as a related group and airing regularly Game of Thrones
Series Episode Episode of a Series The One Where Ross and Rachel Take a Break
Series Preview Extras/Preview/Bonus content Broadway: Extras
Special Special A program produced as one asset; one-time-only program - though it can re-air Inside California Education
Miniseries Miniseries TV Series with storyline resolving within a predefined set of episodes Chernobyl
Miniseries Episode Episode of a Miniseries Part 1
Sports event Team Event Team event of the current season (as of airing time) Kansas City Chiefs at Buffalo Bills
Sports event Sport Event Non-team event of the current season (as of airing time) WM Phoenix Open, Second Round
Sports event Sport Sport series for current season (as of airing time) or spanning multiple seasons NBA Basketball
Sports event Series Legacy/classic sports game series Classic All-Star Wrestling
Sports event Episode Legacy/classic sports game Great Games: San Diego Padres vs. Colorado Rockies
Sports non-event Series Sports-related repeating program NCAA Tournament Postgame
Sports non-event Episode Sports-related episode of a series This Week in Baseball: September 27, 1989
Sports non-event Special Sports-related non-repeating program Hitchins vs. Lemos: Weigh-In
Paid Programming Paid Program Programs produced to sell a product KitchenAid Mixer
TBA TBA No programming or programming info available To Be Announced
Off Air Off Air Station/channel Off Air / no programming available SIGN OFF

The Supplemental Controlled Vocabulary (auto-download) provides a detailed list with more comprehensive definitions and examples.

Titles

Each program provides one or more titles of different types (and languages for the original title type).

XPATH Element/Attribute Description Example
titles/title/ Program title The Sopranos
titles/title/@lang Program title language en, en-GB, es, de, fr-CA
titles/title/@type ”full” should be used for most display purposes. full, original, red, sort, uncensored

In episodes and sports event programs, these fields carry the Series variant title; they are generally referred to as show titles or program titles. The episode or sports event titles in turn are carried by the Episode-specific Elements (see corresponding section below), and are referred to as the episode titles.

Descriptions

XPATH Element/Attribute Description Example
descriptions/desc/ Program description A square yellow sponge lives in the underwater city of Bikini Bottom.
descriptions/desc/@lang Program description language en
descriptions/desc/@type Program description type plot, generic, summary, source

Cast

XPATH Element/Attribute Description Example
cast/member/@ord Cast billing/listing order 01
cast/member/@personId Gracenote unique identifier for the cast member 1366
cast/member/name/@nameId Gracenote unique identifier for a cast member's credited name 1366
cast/member/characterName/ Name of the character portrayed by the cast member Tyler Durden
cast/member/role/@roleId Gracenote cast role identifier 1

Crew

XPATH Element/Attribute Description Example
crew/member/@ord Cast billing/listing order 02
crew/member/@personId Gracenote unique identifier for the crew member 470664
crew/member/name/@nameId Gracenote unique identifier for a crew member's credited name 479539
crew/member/role/@roleId Gracenote crew role identifier 626

Genres

Genre is an optional but well-populated element of a program. Multiple genres can be assigned to programs, generally from more general to more specific. The number of genres can be unlimited and some programs have over a dozen, but the median number of genres is two. Multiple genre assignments do not have weight or relative importance.

Certain genres indicate concepts such as target audience (Children, Adults Only), animation (Animated, Anime), or whether the program is holiday-related (Holiday). There are subsets of genres that are only applied to Movies, scripted programs or Sports programming.

For the full list of genres with definitions, refer to the Supplemental Controlled Vocabulary (auto-download). For programmatic usage, the genres are enumerated in the Controlled Vocabulary endpoint under Genre type.

XPATH Element/Attribute Description Example
genres/genre/ Gracenote genre value associated with the program Thriller, Drama
genres/genre/@genreId Gracenote unique identifier for the genre 19, 9

Ratings

Parental rating is an optional element of a program. Regardless of the program language, the program will typically contain parental ratings from multiple rating bodies of various countries.

The program parental ratings are typically used as a fallback in cases when the parental rating information is missing in the linear schedule or streaming catalog data.

The parental rating data is suitable for display purposes only, and not to be used to drive business logic.

XPATH Element/Attribute Description Example
ratings/rating/@code Rating assigned to program R
ratings/rating/@ratingBodyId Id of the ratings body that issued the rating code 1
ratings/rating/@ratingsBody Organization providing the rating Motion Picture Association
ratings/rating/warning/ Rating body specific advisory Violence and Language

For programmatic usage, the ratings bodies and warnings are enumerated in the Controlled Vocabulary endpoint, under RatingsBody and RatingAdvisory types. Programs may also carry legacy warnings under ratings/advisories elements. These should not be used as they are not associated with a rating body.

Releases

Release information is an optional element of a program. Release dates are typically provided in the country timezone, not GMT. When available, release dates can be used as original air dates in the specific market.

XPATH Element/Attribute Description Example
releases/release/country/ Country code for the country of the release USA, DEU
releases/release/type/ Gracenote release type for theatrical, broadcast, home video Premiere, Wide, Limited
releases/release/date/ Date of the release for the country and type 2009-11-17
releases/release/medium/ Release medium TV, DVD, Theatre, VOD
releases/release/prgSvcId/ Gracenote unique identifier for source/content provider of release 47119

Seasons

For Series with Seasons, this section will contain the list of seasons identifying each season by the seasonId and providing additional season-specific information such as premier/finale dates, cast/crew (in the same format as program cast/crew) as well as imagery (in the same format as program imagery), as available.

XPATH Element/Attribute Description Example
seasons/season/@seasonId Identifier for the season of this series program 194842
seasons/season/@seasonNumber The season number of the series 1
seasons/season/@seasonYear The season year if no season number is available 2007
seasons/season/seasonPremiere/ The season premiere original air date 2008-01-20
seasons/season/seasonFinale/ The season finale original air date 2008-03-09
seasons/season/totalSeasonEpisodes/ Total number of episodes in the season 7
seasons/season/cast/… The season cast, same format as program cast  
seasons/season/crew/… The season crew, same format as program crew  
seasons/season/assets/asset/… The season images  

Video Descriptors

Video Descriptor assignments are an optional element of a program. Descriptors are assigned at the Program root level, i.e. different TMSIds on the same rootId should have the same descriptors. In Series, descriptors are typically assigned to the Series program. The order of descriptor assignments to the program is arbitrary and does not imply importance.

XPATH Element/Attribute Description Example
videoDescriptors/videoDescriptor/@id Gracenote unique id for the Video Descriptor GN5ME6XVY48S4HS
videoDescriptors/videoDescriptor/@weight Video Descriptor weight 9

Other Notable Elements

The following miscellaneous elements can be used in business logic for mapping, filtering, disambiguation, and other purposes.

XPATH Element/Attribute Description Example
origAirDate/ Original air date (non-Movies) 1994-09-22
audioOriginalLang Original audio languages of the program en
originalNetwork/@prgSvcId Network on which the series premiere aired NBC
runTime/ Program duration in ISO-8601 format: PT01H30M (Movies) PT02H19M
duration/ Program duration in minutes (non-Movies) 30
colorCode/ Program color or B/W info color
partNumber/ Multipart program part number 1
totalParts/ Multipart program total parts 2

Movie-specific Elements

XPATH Element/Attribute Description Example
versionLabel/ Unstructured free text field providing additional context for the movie version Unrated, Director's Cut, 70mm
movieInfo/ soundMixes/soundMix Sound mix format used by the movie Mono, Stereo, Magnetic Stereo 6 Track
movieInfo/ pictureFormats/pictureFormat Picture format used by the movie 70mm
movieInfo/ productionCompanies/name Production company for the movie Stanley Kubrick Productions
movieInfo/yearOfRelease Movie year of the release 1968
movieInfo/officialURL Movie's official studio URL  

Episode-specific Elements

The episode title language and subtype usually - but not always - follow the program title language and subtype. For example the market variant of a Series might have an English show title but episode titles in the market language.

XPATH Element/Attribute Description Example
episodeInfo/title/ Episode title Winter Is Coming
episodeInfo/title/@subType Episode title subType Main
episodeInfo/title/@lang Episode title language en
episodeInfo/@number Episode number 1
episodeInfo/@numInSeries Episode sequence number, across all seasons 1
episodeInfo/@season Episode season number 1
episodeInfo/@seasonYear Episode season year 2024

Sports-specific Elements

On Sports Info

XPATH Element/Attribute Description Example
sportsInfo/gameDate/ Scheduled date of the live coverage of the sports event 2024-01-20
sportsInfo/gameTime/ Scheduled local time of the live coverage of the sports event 17:00:00-08:00
sportsInfo/gameTimeZone/ Time zone of the of the sporting event location Pacific Observing
sportsInfo/season/ Single year, or start and end years of the sport's season 2024
sportsInfo/season/@type Type of sports season, pre-, regular, post- Post
sportsInfo/venue/ The official name of the venue Levi's Stadium
sportsInfo/venue/@venueBrandId Gracenote unique identifier for the venue name 1908
sportsInfo/team/ The official name of the sports team San Francisco 49ers
sportsInfo/team/@teamBrandId Gracenote unique identifier for the team name 57
sportsInfo/team/@isHome Boolean designating team as 'home' team in the event true

On Sports Data (GSC)

In the table below, the XPATH for is relative to on/programs/program/sportsData/sportsEvents/SportsEvent

XPATH Element/Attribute Description Example
id/ Gracenote Sports Connected event identifier GNAK4TXGHDSJNQV
type/ Gracenote Sports Connected event type MATCH

Program Relationships

Program relationships associate programs to celebrities, sports organizations or other programs.

Relationships to other programs can be broadly classified as same-program (Custom Version, Alternate Audio, …), or different-program (Derivative, Remake, Crossover, …). The same-program relationships are useful for disambiguating among multiple rootIds and arriving at the “representative” rootId for the program. The different-program relationships are useful for recommendations / related content use cases. Most relationships are directional; the direction is specified in the association value. Please refer to the Supplemental Controlled Vocabulary (auto-download) for individual relationship definitions and examples.

XPATH Element/Attribute Description Example
relationships/relationship/type/ Relationship type Franchise
relationships/relationship/association/ parent, child, peer peer
relationships/relationship/rootId/ Program target 209921
relationships/relationship/label/ Relationship label Battlestar Galactica
relationships/relationship/organizationId/ Organization id target 20
relationships/relationship/personId/ Celebrity id target 100
relationships/relationship/personNameId/ Celebrity name id target 100

Imagery

In the table below, the XPATH for program images is relative to on/programs/program/ and the XPATH for season images is relative to on/programs/program/seasons/season/

XPATH Element/Attribute Description Example
assets/asset/@assetId Gracenote image identifier p173378_p_v10_aa
assets/asset/@type MIME content type image/jpeg
assets/asset/@lastModified Timestamp of last asset/metadata modification 2016-05-11T06:21:00Z
assets/asset/@width Maximum image width 1536
assets/asset/@height Maximum image height 2048
assets/asset/@primary Whether image is primary in the category true
assets/asset/@category Image category Poster Art
assets/asset/@ratio Image aspect ratio. Default program aspect ratios are: 2:3, 3:4, 1:1, 4:3, 16:9, 2:1 3:4
assets/asset/@tier Image tier, usually the subType of the program season
assets/asset/@seasonId For season images, seasonId 7894511
assets/asset/@provider For restricted images, image provider Warner - restricted
assets/asset/URI/ Relative Image URI assets/p173378_p_v10_aa.jpg

The image asset structure and general handling logic is common to images of all entities, however, categories, tiers and aspect ratios vary depending on the entity. The following tables cover most used program image categories, aspect ratios, tiers as well as their prevalence across different program types. For more information, see the supplementary document On API Image Category & Tier Definitions (auto-download). 

Texted image categories

Category Tiers Programs Description Ratios Example
VOD Art - Movies Official art with title graphics * 12
Banner-L1 Series, Season Series Press kit or other image with title graphics * 12
Banner-L1 Sport, Sport Event Sport Events Image representative of sport/league with title * 12
Banner-L2 Team Event Sport Events Represents teams in specific sport/league * 12
Banner-L2 Series Series Gracenote-created stylized title over official or stock image for the program * 12
Poster Art - Movies Movie poster art 2:3, 3:4 12

Textless image categories

Category Tiers Programs Description Ratios Example
Iconic - Movies Scene stills * 12
Iconic Series Series Press kit or other image without title graphics * 12
Iconic Episode Series Episode stills * 12
Iconic Sport Sport Events Image representative of sport/league without title * 12
Key Art - Movies Hero + background image * 12

Referenced CV Lists

The following program value lists are enumerated in the Data Dictionaries and Controlled Vocabulary endpoint:

  • Genre, Ratings, Awards, Cast/Crew Roles, Countries.

The following program value lists are documented in the Supplemental Controlled Vocabulary (auto-download):

  • Program Types/Subtypes, Title Subtypes, Program Relationships, Release Media. The Supplemental Controlled Vocabulary also includes Gracenote Genre descriptions.

Entity Relationship Diagram

The following diagram illustrates the references from a program record to itself, other program types as well as other objects within the On API.

A screenshot of a computer program Description automatically generated

 

  • A generic program will have its TMSId=connectorId and rootId=seriesId. The seriesId is not present for movie programs (progType=Feature Film, TV Movie, Short Film).
  • The Episode program’s connectorId and seriesId will point to the parent Series record TMSId and rootId, respectively. If it exists, the Episode seasonId will point to one of the Seasons contained in the parent Series record.
  • The series can be further grouped into “superseries” whereas the seriesId of the Episodes and of their immediate Series parent will point to the rootId of the Superseries.
  • The program relationship elements can either point to another (related) program via rootId, or to a Sports Organization (organizationId) or a Celebrity (personId and personNameId).
  • A program may point to video descriptor entities
  • Other API entities can reference programs but they are not shown on this diagram

 

TMSId rootId connectorId seriesId seasonId title
MV000118140000 6252 MV000118140000 - - 2001: A Space Odyssey
SH001151270000 183931 SH001151270000 183931 - Friends
EP001151270002 1712254 SH001151270000 183931 7892576 The One With the Thumb
SH000031280000 191277 SH000031280000 191277 - NFL Football
SH049253000000 26058095 SH049253000000 191277 - 2024 Super Bowl
EP049253000001 26058116 SH049253000000 191277 - SF 49ers at KC Chiefs

API and Example Responses

API 

http://on-api.gracenote.com/v3/Programs
?updateId=[updateId value]
&limit=[limit value]
&api_key=[your-api-key]

Request Parameters

Parameter Required? Description
api_key Yes Your API key
updateId No Programs modified at or after updateId.
limit No Batch size. Maximum number of programs to be returned. Use with updateId.
tmsId No For non-batch lookups. 14-char format tmsID. Accepts comma-separated list of TMSIds.
rootId No For non-batch lookups. Supports a single value only. Does not support a comma-separated list of IDs.

Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Example Requests

Return All TMSIds for a Program Using Its Root ID. You can use a Program Root ID instead of TMSIds for Program requests. This returns all of the TMSIds under that Root ID that you are entitled to. 

http://on-api.gracenote.com/v3/Programs?rootId=3554929&api_key=xxxx

Return Full Program Set in Batches of 1000

http://on-api.gracenote.com/v3/Programs?updateId=0&limit=1000&api_key=<your-api-key>

Return Program Data for a Set of TMSIds

http://on-api.gracenote.com/v3/Programs?tmsId=EP002777950623,SH002777950000,EP000031281221,EP000031281286,MV000012490000&api_key=<your-api-key>

Return Program Data for a Single TMSId

http://on-api.gracenote.com/v3/Programs?tmsId=SH002777950000&api_key=<your-api-key>

Example Responses

See Programs XML examples. Also see On API Example Responses

Identifying a Deleted Program

When a Program contains "deleted=true", it indicates that this program is no longer valid and can be deleted from your databases: For more information see Removals (Object Deletion / Inactivation).

Programs Update Requests

When requesting updates, the most recent version of a program is returned. Updates are not 'replayed' as a log of changes.  For example, if a program is added, modified once, and then modified again, the next call for updates includes the program only once in the response, with latest updateId.  updateIds in a response are not consecutive, although programs are sorted by updateId.

Note: In v3/Programs, updateId applies to a TmsId-specific version, so multiple TMSIds with same rootId (language variations of same program) will each be marked with unique updateIds.

Programs Feature Details

This section provides additional information about specific Programs features, including response types and sample output.

Feature Description
Program RoleID Role ID is added to Program cast/crew elements to allow you to lookup language translations for each role in the Controlled Vocabulary. The current role values provided in the cast/crew elements are only English.
IMDb Links To make linking external data easier for customers to support better discovery and navigation, Gracenote will support providing links from TMSIds to IMDb Ids within its programs endpoint output. All TMSIds with the same rootId, will have the same IMDb Id.
Duration A duration value is added when available - this field is a content duration for a time slot including breaks. Another field already available is runTime, which outputs the actual time measurement of the content, not including breaks.
Image Type Branded: Some sources provide Gracenote with program imagery containing their network logo. Once licensed these images will also be made available in the assets block within programs.
Image Type Market: Some sources provide Gracenote with imagery that differs in their market from the imagery Gracenote has collected, usually for the default market or first market that the program was available in or produced for. These images call out the market they are valid for at the programs endpoint.
Image Type Restricted: Gracenote offers a service to clients where we deliver certain restricted images from content providers. Restricted images are images from a specific source/provider who want them to be delivered only to those customers that have a contractual obligation with the source to use these images. Contact your technical account manager to get information about licensing these images.
Referenced Image Size Change http://developer.tmsapi.com/docs/read/media_cloud. 
Title Type Original: The original title type is a way to represent the first title that show/movie was released in. Not all programs will have an original title. 
TMSId Replacements for Long-Running TV Series For certain types of TV series, usually very long running or heavily repackaged shows, there is a limit of 10,000 episodes in the Gracenote database. This is due to the fact that the last 4 digits of the TMSId are reserved for episodic records. For the same series, the limit can be reached earlier for one program language than for another, depending on the number of episodes airing in a given market. Example: "Fireman Sam", Series Root ID: 1732101
  • Series TMSId: SH012693990000
  • Episode TMSId: EP012693990007
Before the limit is reached, Gracenote generates a new TMSId for the series in the applicable program language. The root ID remains the same, but the TMSId changes. The new TMSId will be referenced for any newly created episodes. Example:
  • New Series TMSId: SH036306920000
  • Episode TMSId: EP036306923692
Gracenote will generally use the original and new TMSIds for creation of episodes in sequential order. For example, earlier seasons would reference the original TMSId, and later seasons the new TMSId. However, it is possible for both original and new TMSIds to be referenced in the same season. This is because it is not always possible to create all episodes for a given season at the same time. With children content, repackaging is very common and it is likely that multiple episodes of an earlier season get packaged together years later. These repackaged episodes would still get created under the original season, but may now be using the new TMSId.