-
Notifications
You must be signed in to change notification settings - Fork 5
API 20141201 Program Response
Robert Kulagowski edited this page Jan 15, 2025
·
26 revisions
Your code must be able to process UTF-8 characters.
The response may look like this:
{
"response": "PROGRAMID_QUEUED",
"code": 6001,
"serverID": "20141201.1",
"message": "Fetching programID:SH012423280000 Retry.",
"datetime": "2014-11-14T19:15:54Z"
}
If your program receives this response, it should retry, because a server-side fault occurred and a valid programID should have been available but wasn't, so the server will regenerate the JSON for this programID. This is a soft failure.
If the response looks like this:
{
"response": "INVALID_PROGRAMID",
"code": 6000,
"serverID": "20140530.1",
"message": "Invalid programID:ZZ01234567891234",
"datetime": "2014-11-14T19:17:54Z"
}
then the requested programID is invalid. This is a hard failure.
The rest of this document explains the fields contained in a valid JSON response.
programID: 14 characters. Mandatory.
titles: array containing program titles. Mandatory.
- title120: 120 character description of the program. Mandatory.
- titleLanguage: Optional. However, in a future version of the API, this will be a Mandatory value.
episodeTitle150: 150 character episode title. Optional.
-
descriptions: array containing descriptions of the program. Optional.
-
description100: array containing short description of the program. The description contained will have a maximum of 100 characters. Optional.
-
description1000: array containing long description of the program. The description contained will have a maximum of 1000 characters. Optional. Consists of the following fields:
- descriptionLanguage. Mandatory.
- description: text containing description. Mandatory.
eventDetails: indicates the type of program. Optional. Sport programs will have the following additional information:
Fields:
- venue100: location of the event
- teams: array containing the teams that are playing. Optional.
- name - name of the team. Mandatory.
- "isHome" - boolean indicating this team is the home team. Optional.
- gameDate: YYYY-MM-DD. Optional.
originalAirDate: YYYY-MM-DD. Optional.
genres: array of genres this program falls under. Optional.
officialURL: string containing the official URL of the program. Optional.
keyWords: array containing the following elements:
- Mood. Array of strings. Optional.
- Time Period. Array of strings. Optional.
- Theme. Array of strings. Optional.
- Character. Array of strings. Optional.
- Setting. Array of strings. Optional.
- Subject. Array of strings. Optional.
- General. Array of strings. Optional.
metadata: key / value array of metadata about the program. Optional. Consists of the following fields:
- key - string indicating who is providing the information. Example: "Gracenote"
- value: array consisting of:
- season: integer indicating the season number. Mandatory.
- episode: integer indicating the episode number. Optional.
- totalEpisodes: an integer indicating the total number of episodes. Note: in an "EP" program this indicates the total number of episodes in this season. In an "SH" program, it will indicate the total number of episodes in the series. Optional.
- totalSeasons: integer indicating the total number of seasons in the series. SH programs only. Optional.
entityType: string. Mandatory.
- Compilation
- Episode
- Highlights
- Miniseries
- Movie
- Music Video
- Off Air
- Paid Program
- Preview
- Series
- Short Film
- Show
- Special
- Sport Event
- Sport-Related Episode
- Sports
- Sports
- TBA
- Team Event
- Trailer
- TV Movie
NOTE: Not all sports events will have a leading "SP" programID; your application should use the entity type.
showType: what sort of program is this. Optional.
contentAdvisory: array of advisories about the program, such as adult situations, violence, etc. Optional.
contentRating: array consisting of various rating boards' ratings. Optional. Consists of the following fields:
- body: name of the rating body. Mandatory.
- code: The rating assigned. Dependent on the rating body. Mandatory.
movie: array of information specific to a movie type. Optional, and only found with "MV" programIDs. Consists of the following fields:
- year: YYYY. The year the movie was released. Optional.
- duration: Duration (in integer seconds). Optional. NOTE: in a future API this will be removed from the movie array and will be an element of the program itself.
- qualityRating: an array of ratings for the quality of the movie. Optional. Consists of the following fields:
- ratingsBody: string indicating whose opinion this is. Mandatory.
- rating: string indicating the rating. Mandatory.
- minRating: string indicating the lowest rating. Optional.
- maxRating: string indicating the highest rating. Optional.
- increment: string indicating the increment. Optional.
cast - array of cast members. Optional. Each cast member element consists of the following fields:
- personId: string for this person. Used to retrieve images. Optional.
- nameId: string for this person. Used to differentiate people that have various names, such as due to marriage, divorce, etc. Optional. Actors in adult movies will typically not have a personId or nameId.
- name: string indicating the person's name. Mandatory.
- role: string indicating what role this person had. Mandatory.
- characterName: string indicating the name of the character this person played. Optional.
- billingOrder: string indicating billing order. Mandatory.
crew - array of crew members. Optional. Follows the same pattern as "cast".
recommendations - array of programs similar to this one that you may also enjoy. Optional. Each recommendation element consists of the following fields:
- programID: programID of the recommendation. Mandatory.
- title120: string indicating the name of the similar program. Mandatory.
hasImageArtwork: boolean indicating that there are images available for this program. Optional.
duration: Duration of the program without commercials (in integer seconds). Optional.
episodeImage: Contains a link to an image from this particular episode. Optional.
awards: an array containing elements consisting of the following fields:
- name: string containing the name of the award. Optional.
- awardName: string containing the name of the award. Optional.
- recipient: string containing the name of the recipient. Optional.
- personId: personId of the recipient. Optional.
- won: boolean. Optional.
- year: string. Year of award. Optional.
- category: string. Optional.
md5: md5 hash value of the JSON. Mandatory. This is the 22 character wide version which is the legacy MD5.
hash: 32-character "standard" MD5 hash of the JSON. Optional. However, in a future API, this will be Mandatory, and the "md5" will be removed.
{
"programID": "EP012599310061",
"resourceID": "8100033",
"titles": [
{
"title120": "Hot in Cleveland",
"titleLanguage": "en"
}
],
"descriptions": {
"description1000": [
{
"descriptionLanguage": "en",
"description": "Melanie's hair blow out lasts unusually long; tensions rise among the ladies and the two rival hairdressers at Elka's favorite salon."
}
],
"description100": [
{
"descriptionLanguage": "en",
"description": "Melanie's hair blow out lasts unusually long; tensions rise among the ladies."
}
]
},
"originalAirDate": "2012-06-06",
"showType": "Series",
"entityType": "Episode",
"country": [
"USA"
],
"genres": [
"Sitcom"
],
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"name": "Valerie Bertinelli",
"characterName": "Melanie Moretti",
"nameId": "154",
"personId": "154"
},
{
"billingOrder": "02",
"role": "Actor",
"name": "Betty White",
"characterName": "Elka Ostrovsky",
"nameId": "1918",
"personId": "1918"
},
{
"billingOrder": "03",
"role": "Actor",
"name": "Wendie Malick",
"characterName": "Victoria Chase",
"nameId": "65675",
"personId": "65675"
},
{
"billingOrder": "04",
"role": "Actor",
"name": "Jane Leeves",
"characterName": "Joy Scroggs",
"nameId": "71516",
"personId": "71516"
},
{
"billingOrder": "05",
"role": "Guest Star",
"name": "Elizabeth J. Carlisle",
"characterName": "Shamed Woman",
"nameId": "639710",
"personId": "618197"
},
{
"billingOrder": "06",
"role": "Guest Star",
"name": "Carol Herman",
"characterName": "Mrs. Magee"
},
{
"billingOrder": "07",
"role": "Actor",
"name": "Regis Philbin",
"characterName": "Pierre",
"nameId": "1345",
"personId": "1345"
},
{
"billingOrder": "08",
"role": "Actor",
"name": "David Spade",
"characterName": "Christopher",
"nameId": "15748",
"personId": "15748"
}
],
"contentRating": [
{
"body": "Freiwillige Selbstkontrolle Fernsehen",
"code": "6",
"country": "DEU"
},
{
"body": "USA Parental Rating",
"code": "TVPG",
"country": "USA"
},
{
"body": "Canadian Parental Rating",
"code": "PG",
"country": "CAN"
},
{
"body": "Australian Classification Board",
"code": "PG",
"country": "AUS"
},
{
"body": "Departamento de Justiça, Classificação, Títulos e Qualificação",
"code": "10",
"country": "BRA"
},
{
"body": "Freiwillige Selbstkontrolle der Filmwirtschaft",
"code": "12",
"country": "FIN"
},
{
"body": "Kijkwijzer",
"code": "AL",
"country": "NLD"
}
],
"episodeTitle150": "Blow Outs",
"metadata": [
{
"TVmaze": {
"season": 3,
"episode": 24,
"url": "https://www.tvmaze.com/episodes/32477/hot-in-cleveland-3x24-blow-outs"
}
},
{
"Gracenote": {
"season": 3,
"episode": 24
}
}
],
"duration": 1320,
"hasImageArtwork": true,
"hasEpisodeArtwork": true,
"hasSeasonArtwork": true,
"hasSeriesArtwork": true,
"hash": "1a0e4fac463155130bd989b021fbe646",
"md5": "Gg5PrEYxVRML2YmwIfvmRg"
}
This is the "SH" for the same series:
{
"programID": "SH012599310000",
"resourceID": "8100033",
"titles": [
{
"title120": "Hot in Cleveland",
"titleLanguage": "en"
}
],
"descriptions": {
"description1000": [
{
"descriptionLanguage": "en",
"description": "When their plane has trouble while on a flight to Paris, three glamorous LA women find themselves in a completely new and unexpected place. Feeling the need for a girls-only, once-in-a-lifetime trip, Melanie cashes in her airline miles to finance a trip to the city of light for herself and her two best friends, Joy and Victoria, all \"of a certain age\" and feeling less than desirable. They never make it to Paris, though -- when the stricken plane lands in Cleveland, the women suddenly find they're popular with the men there. Realizing that while they may be lukewarm in LA, they're hot in Cleveland, the women decide to relocate. They immediately fall in love with their rental house. It takes a little longer, however, for them to warm up to the house's longtime caretaker (Betty White)."
}
],
"description100": [
{
"descriptionLanguage": "en",
"description": "Best friends rediscover themselves in Ohio."
}
]
},
"originalAirDate": "2010-06-16",
"showType": "Series",
"entityType": "Series",
"country": [
"USA"
],
"genres": [
"Sitcom"
],
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"name": "Valerie Bertinelli",
"characterName": "Melanie Moretti",
"nameId": "154",
"personId": "154"
},
{
"billingOrder": "02",
"role": "Actor",
"name": "Betty White",
"characterName": "Elka Ostrovsky",
"nameId": "1918",
"personId": "1918"
},
{
"billingOrder": "03",
"role": "Actor",
"name": "Wendie Malick",
"characterName": "Victoria Chase",
"nameId": "65675",
"personId": "65675"
},
{
"billingOrder": "04",
"role": "Actor",
"name": "Jane Leeves",
"characterName": "Joy Scroggs",
"nameId": "71516",
"personId": "71516"
}
],
"crew": [
{
"billingOrder": "01",
"role": "Executive Producer",
"name": "Sean Hayes",
"nameId": "153066",
"personId": "86955"
},
{
"billingOrder": "02",
"role": "Executive Producer",
"name": "Todd Milliner",
"nameId": "646590",
"personId": "624973"
}
],
"contentRating": [
{
"body": "USA Parental Rating",
"code": "TVPG",
"country": "USA"
},
{
"body": "Freiwillige Selbstkontrolle Fernsehen",
"code": "6",
"country": "DEU"
},
{
"body": "Canadian Parental Rating",
"code": "PG",
"country": "CAN"
},
{
"body": "Australian Classification Board",
"code": "PG",
"country": "AUS"
},
{
"body": "Departamento de Justiça, Classificação, Títulos e Qualificação",
"code": "10",
"country": "BRA"
},
{
"body": "Mediakasvatus- ja kuvaohjelmayksikkö",
"code": "K7",
"country": "FIN"
},
{
"body": "Kijkwijzer",
"code": "AL",
"country": "NLD",
"contentWarning": [
"Coarse Language"
]
}
],
"duration": 1800,
"officialURL": "http://www.tvland.com/prime/shows/hot_in_cleveland/",
"hasImageArtwork": true,
"hasSeriesArtwork": true,
"hash": "9e47dd71d00b8a5d5af17e688a75cafa",
"md5": "nkfdcdALil1a8X5oinXK+g"
}
{
"programID": "MV000158920000",
"resourceID": "7719",
"titles": [{
"title120": "Raiders of the Lost Ark",
"titleLanguage": "en"
}],
"descriptions": {
"description1000": [{
"descriptionLanguage": "en",
"description": "Dr. Indiana Jones, a renowned archeologist and expert in the occult, is hired by the U.S. Government to find the ark of the covenant, which is believed to still hold the Ten Commandments. Unfortunately, Hitler's agents are also after the ark. Indy and his ex-flame Marion escape from various close scrapes in a quest that takes them from Nepal to Cairo."
}],
"description100": [{
"descriptionLanguage": "en",
"description": "Indiana Jones (Harrison Ford) braves snakes and Nazis to find the biblical ark of the covenant."
}]
},
"showType": "Feature Film",
"entityType": "Movie",
"country": ["USA"],
"genres": ["Adventure", "Action"],
"cast": [{
"billingOrder": "01",
"role": "Actor",
"name": "Harrison Ford",
"characterName": "Dr. Henry 'Indiana' Jones, Jr.",
"nameId": "25704",
"personId": "25704"
}, {
"billingOrder": "02",
"role": "Actor",
"name": "Karen Allen",
"characterName": "Marion Ravenwood",
"nameId": "35610",
"personId": "35610"
}, {
"billingOrder": "03",
"role": "Actor",
"name": "Paul Freeman",
"characterName": "Rene Belloq",
"nameId": "74672",
"personId": "74672"
}, {
"billingOrder": "04",
"role": "Actor",
"name": "Wolf Kahler",
"characterName": "Dietrich",
"nameId": "170192",
"personId": "169111"
}, {
"billingOrder": "05",
"role": "Actor",
"name": "Ronald Lacey",
"characterName": "Toht",
"nameId": "85233",
"personId": "85233"
}, {
"billingOrder": "06",
"role": "Actor",
"name": "John Rhys-Davies",
"characterName": "Sallah",
"nameId": "67941",
"personId": "67941"
}, {
"billingOrder": "07",
"role": "Actor",
"name": "Denholm Elliott",
"characterName": "Marcus Brody",
"nameId": "83286",
"personId": "83286"
}, {
"billingOrder": "08",
"role": "Actor",
"name": "Anthony Higgins",
"characterName": "Gobler",
"nameId": "151447",
"personId": "151352"
}, {
"billingOrder": "09",
"role": "Actor",
"name": "Alfred Molina",
"characterName": "Sapito",
"nameId": "3584",
"personId": "3584"
}],
"crew": [{
"billingOrder": "01",
"role": "Director",
"name": "Steven Spielberg",
"nameId": "1672",
"personId": "1672"
}, {
"billingOrder": "02",
"role": "Writer",
"name": "Lawrence Kasdan",
"nameId": "884",
"personId": "884"
}, {
"billingOrder": "03",
"role": "Writer (Story)",
"name": "George Lucas",
"nameId": "23344",
"personId": "23344"
}, {
"billingOrder": "04",
"role": "Writer (Story)",
"name": "Philip Kaufman",
"nameId": "162726",
"personId": "162064"
}, {
"billingOrder": "05",
"role": "Executive Producer",
"name": "Howard G. Kazanjian",
"nameId": "473903",
"personId": "465028"
}, {
"billingOrder": "06",
"role": "Executive Producer",
"name": "George Lucas",
"nameId": "23344",
"personId": "23344"
}, {
"billingOrder": "07",
"role": "Producer",
"name": "Frank Marshall",
"nameId": "140145",
"personId": "140145"
}, {
"billingOrder": "08",
"role": "Associate Producer",
"name": "Robert Watts",
"nameId": "446163",
"personId": "437288"
}, {
"billingOrder": "09",
"role": "Original Music",
"name": "John Williams",
"nameId": "533648",
"personId": "516972"
}, {
"billingOrder": "10",
"role": "Cinematography",
"name": "Douglas Slocombe",
"nameId": "473904",
"personId": "465029"
}, {
"billingOrder": "11",
"role": "Film Editing",
"name": "Michael Kahn",
"nameId": "726543",
"personId": "696907"
}, {
"billingOrder": "12",
"role": "Film Editing",
"name": "George Lucas",
"nameId": "23344",
"personId": "23344"
}, {
"billingOrder": "13",
"role": "Film Editing",
"name": "Steven Spielberg",
"nameId": "1672",
"personId": "1672"
}, {
"billingOrder": "14",
"role": "Casting",
"name": "Jane Feinberg"
}, {
"billingOrder": "15",
"role": "Casting",
"name": "Mike Fenton",
"nameId": "473906",
"personId": "465031"
}, {
"billingOrder": "16",
"role": "Casting",
"name": "Mary Selway",
"nameId": "431308",
"personId": "422433"
}, {
"billingOrder": "17",
"role": "Production Designer",
"name": "Norman Reynolds"
}, {
"billingOrder": "18",
"role": "Art Direction",
"name": "Leslie Dilley",
"nameId": "454627",
"personId": "445752"
}, {
"billingOrder": "19",
"role": "Set Decoration",
"name": "Michael Ford"
}, {
"billingOrder": "20",
"role": "Costume Design",
"name": "Deborah Nadoolman",
"nameId": "473907",
"personId": "465032"
}, {
"billingOrder": "21",
"role": "Hair Stylist",
"name": "Mike Lockey"
}, {
"billingOrder": "22",
"role": "Makeup Artist",
"name": "Dickie Mills"
}],
"contentAdvisory": ["Adult Language", "Adult Situations", "Violence"],
"contentRating": [{
"body": "Motion Picture Association",
"code": "PG",
"country": "USA"
}, {
"body": "British Board of Film Classification",
"code": "PG",
"country": "GBR"
}, {
"body": "Ontario Film Authority",
"code": "PG",
"country": "CAN"
}, {
"body": "B.C. Film Classification Office",
"code": "PG",
"country": "CAN",
"contentWarning": ["Violence", "Coarse Language"]
}, {
"body": "Saskatchewan Film and Video Classification Board",
"code": "PG",
"country": "CAN",
"contentWarning": ["Violence", "Coarse Language"]
}, {
"body": "Departamento de Justi\u00e7a, Classifica\u00e7\u00e3o, T\u00edtulos e Qualifica\u00e7\u00e3o",
"code": "L",
"country": "BRA"
}, {
"body": "Manitoba Film Classification Board",
"code": "14A",
"country": "CAN",
"contentWarning": ["Violence"]
}, {
"body": "Maritime Film Classification Board",
"code": "14",
"country": "CAN"
}, {
"body": "Mediakasvatus- ja kuvaohjelmayksikk\u00f6",
"code": "K12",
"country": "FIN"
}, {
"body": "Freiwillige Selbstkontrolle der Filmwirtschaft",
"code": "12",
"country": "FIN"
}, {
"body": "Australian Classification Board",
"code": "M",
"country": "AUS"
}, {
"body": "Film & Publication Board",
"code": "PG",
"country": "ZAF"
}, {
"body": "Ministero della Cultura",
"code": "T",
"country": "ITA"
}, {
"body": "Instituto de Cinematograf\u00eda y de las Artes Visuales",
"code": "TP",
"country": "ESP"
}, {
"body": "Kijkwijzer",
"code": "12",
"country": "NLD",
"contentWarning": ["Violence", "Fear"]
}, {
"body": "Statens medier\u00e5d",
"code": "Fr\u00e5n 15 \u00e5r",
"country": "SWE"
}, {
"body": "R\u00e9gie du cin\u00e9ma",
"code": "G",
"country": "CAN",
"contentWarning": ["Not Rec. for Young Children"]
}, {
"body": "Medietilsynet",
"code": "15 \u00e5r",
"country": "NOR"
}, {
"body": "Direcci\u00f3n General de Radio, Televisi\u00f3n y Cinematograf\u00eda",
"code": "A",
"country": "MEX"
}, {
"body": "\u6620\u502b",
"code": "G",
"country": "JPN"
}, {
"body": "Alberta's Film Classification Board",
"code": "PG",
"country": "CAN",
"contentWarning": ["Coarse Language", "Violence"]
}, {
"body": "\uc601\uc0c1\ubb3c\ub4f1\uae09\uc704\uc6d0\ud68c",
"code": "12+",
"country": "KOR"
}, {
"body": "Krajowa Rada Radiofonii i Telewizji",
"code": "12",
"country": "POL"
}, {
"body": "UK Content Provider",
"code": "PG",
"country": "GBR"
}, {
"body": "Medier\u00e5det",
"code": "11",
"country": "DNK"
}],
"movie": {
"qualityRating": [{
"ratingsBody": "Gracenote",
"rating": "4",
"minRating": "1",
"maxRating": "4",
"increment": ".5"
}],
"year": "1981",
"duration": 6900
},
"officialURL": "http:\/\/www.indianajones.com\/",
"hasImageArtwork": true,
"hasMovieArtwork": true,
"hash": "3dcba7a89242b68bf044408bebc17488",
"md5": "PcunqJJCtovwRECL68F0iA"
}
A Sports event; note that this is not a "SP" programID.
{
"programID": "EP000031283764",
"resourceID": "191277",
"titles": [{
"title120": "NFL Football",
"titleLanguage": "en"
}],
"descriptions": {
"description1000": [{
"descriptionLanguage": "en",
"description": "The Cowboys try to strengthen their grip on the NFC East rival Giants with a fifth straight series victory. Dallas has won 11 of the last 12 meetings. New York running back Saquon Barkley is back in the fold after signing a one-year contract in July."
}],
"description100": [{
"descriptionLanguage": "en",
"description": "The Cowboys try to strengthen their grip on the rival Giants with a fifth straight series win."
}]
},
"originalAirDate": "2023-09-10",
"showType": "Sports event",
"entityType": "Team Event",
"genres": ["Football"],
"episodeTitle150": "Dallas Cowboys at New York Giants",
"eventDetails": {
"gameDate": "2023-09-10",
"venue100": "MetLife Stadium",
"teams": [{
"name": "Dallas Cowboys"
}, {
"name": "New York Giants",
"isHome": true
}]
},
"duration": 10800,
"hasImageArtwork": true,
"hasSportsArtwork": true,
"hasSeriesArtwork": true,
"hash": "44fd4a3558c1f1f857a5ebcd51684ff3",
"md5": "RP1KNVjB8fhXpevNUWhP8w"
}
An "SP" sports event:
{
"programID": "SP003377540000",
"resourceID": "191273",
"titles": [{
"title120": "MLB Baseball",
"titleLanguage": "en"
}],
"descriptions": {
"description1000": [{
"descriptionLanguage": "en",
"description": "From Coors Field in Denver."
}]
},
"originalAirDate": "2016-05-31",
"showType": "Sports event",
"entityType": "Team Event",
"genres": ["Baseball"],
"episodeTitle150": "Cincinnati Reds at Colorado Rockies",
"eventDetails": {
"gameDate": "2016-05-31",
"venue100": "Coors Field",
"teams": [{
"name": "Cincinnati Reds"
}, {
"name": "Colorado Rockies",
"isHome": true
}]
},
"hasImageArtwork": true,
"hasSportsArtwork": true,
"hash": "b70bf6218cc213b7d5cd2988850b465a",
"md5": "twv2IYzCE7fVzSmIhQtGWg"
}