The Programs endpoint provides 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.
Data Structure and Relationships
The Programs XSD schema file is located here:
http://files.api.gracenote.com/xsd/on_update_programs_3.24.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).
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 |
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.
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 |
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.
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.
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 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
Code
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.
Code
Return Full Program Set in Batches of 1000
Code
Return Program Data for a Set of TMSIds
Code
Return Program Data for a Single TMSId
Code
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. |
Programs Alternate Audio Attribute
Alternate Audio is an optional attribute in the Programs endpoint to indicate if an animated program is dubbed in a language other than the original audio language.
For example, the Anime show "Death Note" (rootId: 225665) is produced in Japan, with Japanese being the original audio language. The show was dubbed for the American market, represented by a different show record (rootId: 18936291). The original audio language for the dubbed program is same, but the alternate audio language will be English.
Program records like this are additionally related to each other with a relationship of the type: Alternate Audio in the Programs endpoint.
The schema change for this new attribute will be released on November 12th, and population of the values will likely begin in December of 2025.
Code
ContentFormat Attribute
The optional contentFormat attribute in the Programs endpoint indicates whether a program is "scripted", "unscripted" or "semi-scripted". The field applies to Movies, Shows (Series, Specials, Miniseries) and Episodes, and will be populated whenever possible, utilizing automation that considers the genre or a combination of genres that are applied to the program record. The possible values are defined as follows:
- Scripted: Programs where dialogue, character actions, plot points and scene transitions are pre-written in a detailed script. For example: Action movies, drama series, sitcoms.
- Unscripted: Programs with spontaneous dialogue and action, with no pre-written script. While there might be a general concept or premise, the actual content unfolds organically as events happen and participants react naturally. For example: Documentaries, science shows, interviews, news.
- Semi-Scripted: Programs with a planned general structure or outlined that allow for improvisation and spontaneous dialogue within that framework. For example: Reality shows, talk shows, home improvement programs.
Code
Episode Type Attribute (Repackaging)
Episode Type is an optional attribute in the Programs endpoint to provide more details about the type of an episode for a subset of genres. This metadata attribute will be utilized to indicate episodes that are non-standard episodes in the context of a regular series with a hierarchical structure of series - season - episode.
For applicable episodes, the episodeType element will be populated with one of the following values:
- Split: Indicates that an original "full" episode was split into 2 (or more) episode parts.
- Merged: Indicates that 2 (or more) original "full" episodes have been merged into one episode.
- Derivative: Indicates "special" episodes that relate to the series, or a specific season or episode within the series. For example: Bonus, Extras, Behind the Scenes, Sneak Peek
Examples:
| series_tms_id | series_title | season_# | episode_# | episode_tms_id | episode_title | episode_type |
|---|---|---|---|---|---|---|
| SH033732190000 | Hunters | 1 | 1 | EP033732190001 | In the Belly of the Whale | - |
| SH033732190000 | Hunters | 1 | - | EP033732190020 | In the Belly of the Whale | Split |
| SH033732190000 | Hunters | 1 | - | EP033732190021 | In the Belly of the Whale | Split |
| SH006656510000 | Peppa Pig | 7 | 18 | EP012847870849 | Jelly | - |
| SH006656510000 | Peppa Pig | 8 | 6 | EP006656512720 | Cardboard Boxes | - |
| SH006656510000 | Peppa Pig | - | - | EP006656517760 | Jelly; Cardboard Boxes | Merged |
| SH014661780000 | American Horror Story | 1 | 3 | EP014661780005 | Murder House | - |
| SH014661780000 | American Horror Story | 1 | - | EP014661780006 | Murder House: Three-Minute-Replay | Derivative |
In addition to the tagging of the episodeType, episodes with a type of "Split" or "Merged" will also be automatically related to their full episode counterpart(s) wherever possible. This linking will be done through the existing relationship element in the On API Programs endpoint, with a relationship of the type: Repackage. This will allow you to know which full episodes are combined in a merged episode record, and which split episodes make up a full episode record.
For all three episodeType values, the genres in scope are: Children, Family, Animated, Anime, Live action/animated, Live action/anime, Comedy Drama, Crime Drama, Drama, Family, Reality, Fantasy, Educational.
Code