Program Data Structure without External ID
program data structure without external id the following table describes the program data structure without external id field type mandatory description program_id string true unique identifier of the program across your entire video content catalog program ids must not be duplicated in the feed playback_items list of playbackitems true with exception video playback items with all available options defined with the playbackitem data structure ※ exception • trailer data does not require this field • the "season" and "show" program types do not require this field, except for a standalone "show" program without any related episode content, which does require this field type string true program type • "show" this type has two meanings 1 a single tv show 2 a series of programs the parent of seasons/episodes • "season" a season of a show • "episode" an episode of a season • "movie" movie content • "music" music service content note • if your content is a tv show, it should follow the show-season-episode hierarchy, and the type value should be one of those • if your content is a movie, the type value should be "movie" • the "music" program type is restricted to music-only content without accompanying video, or to music video content exclusively do not use the "music" program type simply because a program is music-related; doing so may result in exclusion from content recommendations and service exposure subtype string false additional predefined subtype keyword defined in the subtype list series_info json object true with exception indicates the program id of the parent program show/season and the season/episode number defined with the seriesinfo data structure ※ exception the "show", "movie", and "music" program types do not require this field titles list of titles true official titles of the video content defined with the title data structure every program must have at least one "main" type title "short" type titles are optional note do not provide multiple "main" or "short" titles for the same language only one "main" and one "short" title are allowed per language descriptions list of descriptions false descriptions or synopses of the video content defined with the description data structure note do not provide multiple descriptions for the same language only one description is allowed per language images list of images true images of the video content defined with the image data structure note do not provide the same image more than once in a program each image url must be unique within a program parental_ratings list of parentalratings false program content ratings, as assigned by national content rating organizations defined with the parentalrating data structure genres list of strings false representative genres of the program multiple genres are acceptable, in decreasing order of importance the supported genres are defined in genre field enums release_date string false release date or year of the program for "show", "season", and "episode" "yyyy-mm-dd" for "movie" "yyyy" or "yyyy-mm-dd" running_time integer false program running time, in seconds casts list of casts false cast and credit list of the program defined with the cast data structure note cast data can be provided only when the program type is "movie" or "show" promotion_score integer false a promotion score assigned by your service to this program, from 1 lowest to 99999 highest the higher the value, the greater the chance that this program will be exposed in our content discovery services table 1 program data structure without external id subtype the subtypes in the following table have been defined by mutual agreement; subtypes that have not been agreed upon in advance are not accepted name description notes sports event sports match programs such as "epl", "mlb", and "formula 1" by adding this subtype, the program can be exposed by the search service even if it is episode-type content this subtype is for actual sports event content only do not add it to sports-related programs such as sports talk shows or sports documentaries note the "sports event" subtype is allowed only when the program type is "show", "season", or "episode" do not use it with the "movie" type table 2 subtypes seriesinfo the seriesinfo data structure is required if the program type is "season" or "episode" it is used to organize content into groups based on shows and seasons notedo not provide this field when the program type is "movie", "show", or "music" field type mandatory description show_id string true unique id of the parent show program season_id string false with exception unique id of the parent season program ※ exception the "episode" program type requires this field season_number integer false with exception season number of the program ※ exception the "season" program type requires this field episode_number integer false with exception episode number of the program ※ exception the "episode" program type requires this field table 3 seriesinfo data structure example for a "season" type { "type" "season", "series_info" { "show_id" "gt29085", "season_number" 33 } } example for an "episode" type { "type" "episode", "series_info" { "show_id" "gt29085", "season_id" "23456", "episode_number" 1 } } title the titles array defines the program titles with the title data structures you can define main and short titles for multiple languages notedo not provide multiple "main" or "short" titles for the same language only one "main" and one "short" title are allowed per language field type mandatory description title string true program title language string true title language, in iso 639-1 format 2-letter language codes see mandatory language type string true title type • "main" official program title text mandatory • "short" well-known abbreviated title text optional table 4 title data structure mandatory language if the program has multiple countries in its playbackitems, it must provide a title in the mandatory language of each country noteto enhance the user experience, also provide descriptions and banner images in the mandatory language of each country country mandatory language language code us english en ca english, french, or french canada en, fr, fr-ca fr french fr gb english en it italian it de german de es spanish es in english en kr korean ko table 5 mandatory languages example { "titles" [ { "title" "game of thrones", "language" "en", "type" "main" } ] } description the descriptions array defines the program descriptions with the description data structures notedo not provide multiple descriptions for the same language only one description is allowed per language field type mandatory description description string true program description language string true description language, in iso 639-1 format 2-letter language codes see mandatory language table 6 description data structure example { "descriptions" [ { "description" "game of thrones is roughly based on the storylines of a song of ice and fire, set in the fictional seven kingdoms of westeros and the continent of essos the series chronicles the violent dynastic struggles among the realm's noble families for the iron throne, while other families fight for independence from it ", "language" "en" } ] } image the images array defines the representative images of the program with the image data structures you can define images for multiple languages each program must have at least one image a landscape image must be at least 928 pixels wide and 522 pixels high a portrait image must be at least 522 pixels high notedo not provide the same image more than once in a program each image url must be unique within a program field type mandatory description url string true url of the image it must be publicly accessible note the image url protocol must be https width integer true image width, in pixels height integer true image height, in pixels type string true image type • "banner" an image with text on it, such as the program title • "iconic" an image without any text on it language string true with exception language of the text on the image, in iso 639-1 format 2-letter language codes see mandatory language ※ exception the "iconic" image type does not require this field table 7 image data structure example { "images" [ { "url" "https //my image cdn/my/image/file jpg", "width" 1920, "height" 1080, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/file2 jpg", "width" 1920, "height" 1080, "type" "iconic" } ] } parentalrating the parental_ratings array defines the program content ratings, as assigned by a national content rating organization, with the parentalrating data structures you can define ratings for multiple countries and organizations field type mandatory description country_code string true country to which the rating applies, in iso 3166-1 alpha-2 format 2-letter country codes body string true rating organization that issued the rating this must match one of the supported rating organizations for the country code string true content rating code issued by the organization this must match one of the supported rating codes for the country table 8 parentalrating data structure the following rating organizations and codes are supported country program type rating organization rating codes us movie mpaa g, pg, pg-13, r, nc-17 show/season/episode usa parental rating tv-y, tv-y7, tv-g, tv-pg, tv-14, tv-ma ca movie/show/season/episode cpr c, c8, g, pg, 14+, 18+ movie/show/season/episode cqc stc, g, 8 ans+, 13 ans+, 16 ans+, 18 ans+ kr movie/show/season/episode korean tv rating all, 7+, 12+, 15+, 19+ gb bbfc u, pg, 12, 12a, 15, 15a, 18, r18, nr fr cnc tous, 10, 12, 16, 18 de fsk fsk 0, fsk 3, fsk 6, fsk 12, fsk 16, fsk 18 es mcu 7, 10, 12, 13, 16, 18, ¡a, a, x it mibac 10, 12, 14, 16, 18, t in cbfc u, u/a, a, s au acb g, pg, m, ma 15+, r 18+ table 9 content rating organizations and codes example { "parental_ratings" [ { "country_code" "us", "body" "mpaa", "code" "pg-13" } ] } cast the casts array defines the cast and credit information of the program with the cast data structures notecast data can be provided only when the program type is "movie" or "show" field type mandatory description name string true real name of the person role string true role type • "actor" • "director" • "music" character_name string false name of the character portrayed table 10 cast data structure example { "type" "show", "casts" [ { "name" "kit harington", "role" "actor", "character_name" "jim hanry" }, { "name" "emilia clarke", "role" "director" }, { "name" "lady gaga", "role" "music" } ] } feed samples the following example feeds define program metadata without an external id example json feed without external id { "programs" [ { "program_id" "12335", "playback_items" [ { "deeplink_payload" "content_id=12335", "country_code" "us", "license" "purchase", "price" 10 99, "currency" "usd", "quality" "fhd", "audio_languages" ["en", "es"], "subtitle_languages" ["en", "es"], "available_starting" "2019-04-14 00 00 00", "available_ending" "2020-04-14 16 00 00", "attributes" ["live_ott", "hdr10+"], "geo_restrictions" { "access_type" "deny", "type" "area", "value" [ { "region" "texas", "city" ["el paso"] }, { "region" "california", "city" ["san diego", "san francisco"] } ] } }, { "deeplink_payload" "content_id=12559", "country_code" "us", "license" "subscription", "quality" "fhd", "audio_languages" ["en"], "subtitle_languages" ["en"], "available_starting" "2025-03-17 16 00 00", "available_ending" "2025-03-17 17 30 00", "attributes" ["live_ott", "hdr10+"], "geo_restrictions" { "access_type" "deny", "type" "area", "value" [ { "region" "texas", "city" ["el paso"] }, { "region" "california", "city" ["san diego", "san francisco"] } ] } }, { "deeplink_payload" "content_id=67890", "country_code" "it", "license" "subscription", "quality" "hd", "audio_languages" ["en", "it"], "available_starting" "2022-01-15 19 13 00", "available_ending" "2022-05-22 23 59 00" } ], "type" "episode", "series_info" { "show_id" "gt29085", "season_id" "23456", "episode_number" 1 }, "titles" [ { "title" "game of thrones", "language" "en", "type" "main" }, { "title" "got", "language" "en", "type" "short" }, { "title" "il trono di spade", "language" "it", "type" "main" } ], "descriptions" [ { "description" "game of thrones is roughly based on the storylines of a song of ice and fire, set in the fictional seven kingdoms of westeros and the continent of essos the series chronicles the violent dynastic struggles among the realm's noble families for the iron throne, while other families fight for independence from it ", "language" "en" } ], "images" [ { "url" "https //my image cdn/my/image/file jpg", "width" 1920, "height" 1080, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/file2 jpg", "width" 1920, "height" 1080, "type" "iconic" } ], "parental_ratings" [ { "country_code" "us", "body" "usa parental rating", "code" "tv-ma" } ], "genres" ["action", "adventure", "fantasy"], "release_date" "2019-04-14", "running_time" 4524, "promotion_score" 789 } ] } example xml feed without external id <?xml version="1 0" encoding="utf-8"?> <programs> <program> <program_id>12335</program_id> <playback_items> <playback_item> <deeplink_payload>content_id=12335</deeplink_payload> <country_code>us</country_code> <license>purchase</license> <price>10 99</price> <currency>usd</currency> <quality>fhd</quality> <audio_languages> <audio_language>en</audio_language> <audio_language>es</audio_language> </audio_languages> <subtitle_languages> <subtitle_language>en</subtitle_language> <subtitle_language>es</subtitle_language> </subtitle_languages> <available_starting>2019-04-14 00 00 00</available_starting> <available_ending>2020-04-14 16 00 00</available_ending> <attributes> <attribute>live_ott</attribute> <attribute>hdr10+</attribute> </attributes> <geo_restrictions> <access_type>deny</access_type> <type>area</type> <value> <area_object> <region>texas</region> <city> <city_object>el paso</city_object> </city> </area_object> <area_object> <region>california</region> <city> <city_object>san diego</city_object> <city_object>san francisco</city_object> </city> </area_object> </value> </geo_restrictions> </playback_item> <playback_item> <deeplink_payload>content_id=12559</deeplink_payload> <country_code>us</country_code> <license>subscription</license> <quality>fhd</quality> <audio_languages> <audio_language>en</audio_language> </audio_languages> <subtitle_languages> <subtitle_language>en</subtitle_language> </subtitle_languages> <available_starting>2025-03-17 16 00 00</available_starting> <available_ending>2025-03-17 17 30 00</available_ending> <attributes> <attribute>live_ott</attribute> <attribute>hdr10+</attribute> </attributes> <geo_restrictions> <access_type>deny</access_type> <type>area</type> <value> <area_object> <region>texas</region> <city> <city_object>el paso</city_object> </city> </area_object> <area_object> <region>california</region> <city> <city_object>san diego</city_object> <city_object>san francisco</city_object> </city> </area_object> </value> </geo_restrictions> </playback_item> <playback_item> <deeplink_payload>content_id=67890</deeplink_payload> <country_code>it</country_code> <license>subscription</license> <quality>hd</quality> <audio_languages> <audio_language>en</audio_language> <audio_language>it</audio_language> </audio_languages> <available_starting>2022-01-15 19 13 00</available_starting> <available_ending>2022-05-22 23 59 00</available_ending> </playback_item> </playback_items> <type>episode</type> <series_info> <show_id>gt29085</show_id> <season_id>23456</season_id> <episode_number>1</episode_number> </series_info> <titles> <title_object> <title>game of thrones</title> <language>en</language> <type>main</type> </title_object> <title_object> <title>got</title> <language>en</language> <type>short</type> </title_object> <title_object> <title>il trono di spade</title> <language>it</language> <type>main</type> </title_object> </titles> <descriptions> <description_object> <description>game of thrones is roughly based on the storylines of a song of ice and fire, set in the fictional seven kingdoms of westeros and the continent of essos the series chronicles the violent dynastic struggles among the realm's noble families for the iron throne, while other families fight for independence from it </description> <language>en</language> </description_object> </descriptions> <images> <image> <url>https //my image cdn/my/image/file jpg</url> <width>1920</width> <height>1080</height> <type>banner</type> <language>en</language> </image> <image> <url>https //my image cdn/my/image/file2 jpg</url> <width>1920</width> <height>1080</height> <type>iconic</type> </image> </images> <parental_ratings> <parental_rating> <country_code>us</country_code> <body>usa parental rating</body> <code>tv-ma</code> </parental_rating> </parental_ratings> <genres> <genre>action</genre> <genre>adventure</genre> <genre>fantasy</genre> </genres> <release_date>2019-04-14</release_date> <running_time>4524</running_time> <promotion_score>789</promotion_score> </program> </programs> the following example feeds define program metadata with a three-level hierarchy show - season - episode without an external id example json feed with 3 depths without external id { "programs" [ { "program_id" "abc-12345-001", "titles" [ { "title" "premier league live", "language" "en", "type" "main" } ], "descriptions" [ { "description" "the premier league is the highest level of the english football league system contested by 20 clubs, it operates on a system of promotion and relegation with the english football league efl ", "language" "en" } ], "images" [ { "url" "https //my image cdn/my/image/banner1 jpg", "width" 1280, "height" 720, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/iconic1 jpg", "width" 1280, "height" 720, "type" "iconic" } ], "genres" ["soccer", "football"], "type" "show", "subtype" "sports event" }, { "program_id" "abc-12345-002", "titles" [ { "title" "premier league 2024/25", "language" "en", "type" "main" } ], "descriptions" [ { "description" "the 2024/25 season of the premier league, the top tier of english football ", "language" "en" } ], "images" [ { "url" "https //my image cdn/my/image/banner2 jpg", "width" 1280, "height" 720, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/iconic2 jpg", "width" 1280, "height" 720, "type" "iconic" } ], "genres" ["soccer", "football"], "type" "season", "subtype" "sports event", "series_info" { "show_id" "abc-12345-001", "season_number" 33 } }, { "program_id" "abc-12345-003", "playback_items" [ { "deeplink_payload" "content_id=abc-12345-003", "country_code" "us", "license" "subscription", "quality" "fhd", "audio_languages" ["en"], "subtitle_languages" ["en"], "available_starting" "2024-10-06 12 50 00", "available_ending" "2024-10-06 15 00 00", "attributes" ["live_ott", "hdr10+"] } ], "titles" [ { "title" "chelsea vs nott'm forest", "language" "en", "type" "main" } ], "descriptions" [ { "description" "chelsea is playing against nott'm forest ", "language" "en" } ], "images" [ { "url" "https //my image cdn/my/image/banner3 jpg", "width" 1280, "height" 720, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/iconic3 jpg", "width" 1280, "height" 720, "type" "iconic" } ], "genres" ["soccer", "football"], "running_time" 7800, "type" "episode", "subtype" "sports event", "series_info" { "show_id" "abc-12345-001", "season_id" "abc-12345-002", "episode_number" 101 } }, { "program_id" "abc-12345-004", "playback_items" [ { "deeplink_payload" "content_id=abc-12345-004", "country_code" "us", "license" "subscription", "quality" "fhd", "audio_languages" ["en"], "subtitle_languages" ["en"], "available_starting" "2024-10-06 20 00 00", "available_ending" "2024-10-06 22 00 00", "attributes" ["live_ott", "hdr10+"] } ], "titles" [ { "title" "lexington sc vs ascent fc", "language" "en", "type" "main" } ], "descriptions" [ { "description" "lexington sc is playing against ascent fc ", "language" "en" } ], "images" [ { "url" "https //my image cdn/my/image/banner4 jpg", "width" 1280, "height" 720, "type" "banner", "language" "en" }, { "url" "https //my image cdn/my/image/iconic4 jpg", "width" 1280, "height" 720, "type" "iconic" } ], "genres" ["soccer", "football"], "running_time" 7200, "type" "episode", "subtype" "sports event", "series_info" { "show_id" "abc-12345-001", "season_id" "abc-12345-002", "episode_number" 102 } } ] } example xml feed with 3 depths without external id <?xml version="1 0" encoding="utf-8"?> <programs> <program> <program_id>abc-12345-001</program_id> <titles> <title_object> <title>premier league live</title> <language>en</language> <type>main</type> </title_object> </titles> <descriptions> <description_object> <description>the premier league is the highest level of the english football league system contested by 20 clubs, it operates on a system of promotion and relegation with the english football league efl </description> <language>en</language> </description_object> </descriptions> <images> <image> <url>https //my image cdn/my/image/banner1 jpg</url> <width>1280</width> <height>720</height> <type>banner</type> <language>en</language> </image> <image> <url>https //my image cdn/my/image/iconic1 jpg</url> <width>1280</width> <height>720</height> <type>iconic</type> </image> </images> <genres> <genre>soccer</genre> <genre>football</genre> </genres> <type>show</type> <subtype>sports event</subtype> </program> <program> <program_id>abc-12345-002</program_id> <titles> <title_object> <title>premier league 2024/25</title> <language>en</language> <type>main</type> </title_object> </titles> <descriptions> <description_object> <description>the 2024/25 season of the premier league, the top tier of english football </description> <language>en</language> </description_object> </descriptions> <images> <image> <url>https //my image cdn/my/image/banner2 jpg</url> <width>1280</width> <height>720</height> <type>banner</type> <language>en</language> </image> <image> <url>https //my image cdn/my/image/iconic2 jpg</url> <width>1280</width> <height>720</height> <type>iconic</type> </image> </images> <genres> <genre>soccer</genre> <genre>football</genre> </genres> <type>season</type> <subtype>sports event</subtype> <series_info> <show_id>abc-12345-001</show_id> <season_number>33</season_number> </series_info> </program> <program> <program_id>abc-12345-003</program_id> <playback_items> <playback_item> <deeplink_payload>content_id=abc-12345-003</deeplink_payload> <country_code>us</country_code> <license>subscription</license> <quality>fhd</quality> <audio_languages> <audio_language>en</audio_language> </audio_languages> <subtitle_languages> <subtitle_language>en</subtitle_language> </subtitle_languages> <available_starting>2024-10-06 12 50 00</available_starting> <available_ending>2024-10-06 15 00 00</available_ending> <attributes> <attribute>live_ott</attribute> <attribute>hdr10+</attribute> </attributes> </playback_item> </playback_items> <titles> <title_object> <title>chelsea vs nott'm forest</title> <language>en</language> <type>main</type> </title_object> </titles> <descriptions> <description_object> <description>chelsea is playing against nott'm forest </description> <language>en</language> </description_object> </descriptions> <images> <image> <url>https //my image cdn/my/image/banner3 jpg</url> <width>1280</width> <height>720</height> <type>banner</type> <language>en</language> </image> <image> <url>https //my image cdn/my/image/iconic3 jpg</url> <width>1280</width> <height>720</height> <type>iconic</type> </image> </images> <genres> <genre>soccer</genre> <genre>football</genre> </genres> <running_time>7800</running_time> <type>episode</type> <subtype>sports event</subtype> <series_info> <show_id>abc-12345-001</show_id> <season_id>abc-12345-002</season_id> <episode_number>101</episode_number> </series_info> </program> <program> <program_id>abc-12345-004</program_id> <playback_items> <playback_item> <deeplink_payload>content_id=abc-12345-004</deeplink_payload> <country_code>us</country_code> <license>subscription</license> <quality>fhd</quality> <audio_languages> <audio_language>en</audio_language> </audio_languages> <subtitle_languages> <subtitle_language>en</subtitle_language> </subtitle_languages> <available_starting>2024-10-06 20 00 00</available_starting> <available_ending>2024-10-06 22 00 00</available_ending> <attributes> <attribute>live_ott</attribute> <attribute>hdr10+</attribute> </attributes> </playback_item> </playback_items> <titles> <title_object> <title>lexington sc vs ascent fc</title> <language>en</language> <type>main</type> </title_object> </titles> <descriptions> <description_object> <description>lexington sc is playing against ascent fc </description> <language>en</language> </description_object> </descriptions> <images> <image> <url>https //my image cdn/my/image/banner4 jpg</url> <width>1280</width> <height>720</height> <type>banner</type> <language>en</language> </image> <image> <url>https //my image cdn/my/image/iconic4 jpg</url> <width>1280</width> <height>720</height> <type>iconic</type> </image> </images> <genres> <genre>soccer</genre> <genre>football</genre> </genres> <running_time>7200</running_time> <type>episode</type> <subtype>sports event</subtype> <series_info> <show_id>abc-12345-001</show_id> <season_id>abc-12345-002</season_id> <episode_number>102</episode_number> </series_info> </program> </programs>